@kaizenreport/kensho-go 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Ordoñez
+
+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,129 @@
+# @kaizenreport/kensho-go
+
+Convert `go test -json` output into a [Kensho v1](../schema) results bundle so
+the Kensho CLI can render a rich static HTML report.
+
+Go's standard test runner has no plugin system, so this adapter ships as a
+**Node-based CLI** that consumes the structured JSON `go test` already emits.
+Drop the optional `go-helper` module into your test code if you want
+first-class steps, attachments, labels and links — same shape as
+`kensho-pytest` and the JS adapters.
+
+## One-liner
+
+```bash
+go test -json ./... | npx kensho-go --output kensho-results
+npx kensho generate
+npx kensho open
+```
+
+## Install
+
+```bash
+pnpm add -D @kaizenreport/kensho-go @kaizenreport/kensho
+# or
+npm install --save-dev @kaizenreport/kensho-go @kaizenreport/kensho
+```
+
+## Usage
+
+```bash
+# pipe the JSON stream straight in
+go test -json ./... | npx kensho-go --output kensho-results
+
+# or save it first (handy in CI for re-runnable conversions)
+go test -json ./... > gotest.json
+npx kensho-go --input gotest.json --output kensho-results
+
+# merge multiple files
+npx kensho-go --input unit.json --input integration.json --output kensho-results
+```
+
+| Flag                            | Effect                                                    |
+| ------------------------------- | --------------------------------------------------------- |
+| `--input <file>`, `-i`          | Read events from a file. Pass multiple times to merge.    |
+| `--output <dir>`, `-o`          | Output directory (default `kensho-results`).              |
+| `--project-name <name>`         | Project name to embed in `run.json`.                      |
+| `--project-slug <slug>`         | Project slug for the platform.                            |
+| `--run-id <id>`                 | Override the auto-generated run id.                       |
+| `--subtests cases\|children`    | `cases` (default) — every `t.Run` becomes its own case. `children` — sub-tests roll up as nested steps under the parent. |
+
+## Mapping (`go test -json` → Kensho)
+
+| Action       | Effect                                                        |
+| ------------ | ------------------------------------------------------------- |
+| `run`        | Open a case (or sub-case) with its `startedAt`.               |
+| `output`     | Append the line to `case.logs[]`. `KENSHO_META:` lines from the helper module are parsed out separately. |
+| `pass`       | Close the case with `status: 'pass'` and `duration` from `Elapsed`. |
+| `fail`       | Close with `status: 'fail'`. The captured output becomes `errors[].stack`. |
+| `skip`       | Close with `status: 'skip'`.                                  |
+| `panic:` in output | Forces `status: 'fail'` (Go has no `broken` concept; the converter reserves it for events with no terminal action — usually a build failure). |
+
+Stable case IDs come from `<Package>::<Test>` hashed via the same FNV-1a-based
+algorithm the JS adapters use, so a Go package's history lines up with other
+runs of the same suite on the platform.
+
+Severity is detected from the test name (`Test_blocker_*`, `Test_critical_*`,
+…) or from sub-test names (`t.Run("severity:critical", …)`, `t.Run("@critical")`).
+Inline `@tag` substrings in the test name become `case.tags`.
+
+## Optional Go helper module
+
+For first-class metadata, drop the helper module under `packages/go/go-helper/`
+into your project (it's a separate Go module — `go get` it directly from this
+repo, or vendor it):
+
+```go
+package mything
+
+import (
+    "testing"
+    kensho "github.com/kaizenreport/kensho-go-helper"
+)
+
+func TestLoginHappyPath(t *testing.T) {
+    kensho.Severity(t, "critical")
+    kensho.Feature(t, "Authentication")
+    kensho.Label(t, "team", "growth")
+    kensho.Link(t, "https://jira.example.com/browse/PROJ-123",
+        kensho.LinkOpts{Kind: "jira", Label: "PROJ-123"})
+
+    kensho.Step(t, "open the login page", func() {
+        kensho.Step(t, "warm up CDN", func() {
+            // …
+        })
+    })
+
+    kensho.Step(t, "submit credentials", func() {
+        // …
+    })
+
+    kensho.Attach(t, "/tmp/login.png", kensho.AttachOpts{Kind: "screenshot"})
+}
+```
+
+| Helper                                     | What it does                                            |
+| ------------------------------------------ | ------------------------------------------------------- |
+| `kensho.Step(t, title, func() { … })`      | Opens a Kensho step. Nests automatically. Marks `fail` on panic or `t.Failed()`. |
+| `kensho.Attach(t, path, opts…)`            | Registers a file. The Node CLI copies it into `kensho-results/attachments/<caseId>/`. |
+| `kensho.Label(t, key, value)`              | Adds a free-form `key=value` to `case.labels`.          |
+| `kensho.Link(t, url, opts…)`               | Adds a hyperlink.                                       |
+| `kensho.Severity(t, value)`                | Sets `case.severity`.                                   |
+| `kensho.Feature/Epic/Scenario(t, value)`   | Populates `case.behavior.*`.                            |
+| `kensho.Tag(t, value)`                     | Adds a tag.                                             |
+| `kensho.Parameter(t, name, value, opts…)`  | Records a parameter (table-driven inputs).              |
+
+The helper writes nothing to stdout — only `KENSHO_META: {...}` lines via
+`t.Logf`. Outside of `go test -json` the lines are harmless test log output.
+
+## Why a Node CLI?
+
+Go's std `testing` package doesn't expose a plugin / reporter API, but
+`go test -json` is a stable, structured stream. Routing through the same
+Node CLI used by the rest of the toolchain keeps the install footprint
+zero-Go-dependency for the converter and zero-Node-dependency for users
+who only want the helper module.
+
+## License
+
+Apache-2.0.

package/bin/kensho-go.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// kensho-go — convert `go test -json` output into kensho-results/.
+//
+//   go test -json ./... | npx kensho-go --output kensho-results
+//   npx kensho-go --input gotest.json --output kensho-results
+//
+// Then:
+//
+//   npx kensho generate
+//   npx kensho open
+
+import { convertGoEvents, readEvents, readEventsFromStream } from '../src/index.js';
+
+function parseArgs(argv) {
+  const out = {
+    inputs: [],
+    output: 'kensho-results',
+    subtests: 'cases',
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--input' || a === '-i') out.inputs.push(argv[++i]);
+    else if (a === '--output' || a === '-o') out.output = argv[++i];
+    else if (a === '--project-name') out.projectName = argv[++i];
+    else if (a === '--project-slug') out.projectSlug = argv[++i];
+    else if (a === '--run-id') out.runId = argv[++i];
+    else if (a.startsWith('--subtests=')) out.subtests = a.slice('--subtests='.length);
+    else if (a === '--subtests') out.subtests = argv[++i];
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (!a.startsWith('-')) out.inputs.push(a);
+  }
+  return out;
+}
+
+const argv = parseArgs(process.argv.slice(2));
+
+if (argv.help) {
+  console.log(`Usage: kensho-go [--input <file>] [--output kensho-results]
+                 [--project-name <name>] [--project-slug <slug>]
+                 [--run-id <id>] [--subtests cases|children]
+
+Reads \`go test -json\` events and writes a kensho-results/ bundle.
+
+Common flows:
+
+  go test -json ./... | npx kensho-go --output kensho-results
+  npx kensho-go --input gotest.json --output kensho-results
+
+Options:
+  --input, -i        Path to a file with go test -json output (omit to read stdin).
+                     Pass --input multiple times to merge several files.
+  --output, -o       Output directory (default: kensho-results).
+  --project-name     Project name to embed in run.json (default: "Unknown project").
+  --project-slug     Project slug (default: derived from name or "unknown").
+  --run-id           Override the auto-generated run id.
+  --subtests         "cases" (default) — every \`t.Run\` becomes its own Kensho case.
+                     "children"        — sub-tests roll up as nested steps under the parent.
+
+After conversion, render the report with the Kensho CLI:
+
+  npx kensho generate
+  npx kensho open
+`);
+  process.exit(0);
+}
+
+(async () => {
+  let events;
+  try {
+    if (argv.inputs.length) {
+      events = readEvents(argv.inputs.length === 1 ? argv.inputs[0] : argv.inputs);
+    } else if (!process.stdin.isTTY) {
+      events = await readEventsFromStream(process.stdin);
+    } else {
+      console.error('[kensho-go] no input. Pipe `go test -json` output in, or pass --input <file>.');
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error('[kensho-go] failed to read input:', e && e.message);
+    process.exit(2);
+  }
+
+  if (!events.length) {
+    console.error('[kensho-go] no events parsed — is the input actually `go test -json` output?');
+    process.exit(3);
+  }
+
+  try {
+    const res = convertGoEvents({
+      events,
+      output: argv.output,
+      project: { name: argv.projectName, slug: argv.projectSlug },
+      runId: argv.runId,
+      subtests: argv.subtests,
+    });
+    if (!res.valid) process.exit(4);
+  } catch (e) {
+    console.error('[kensho-go] conversion failed:', e && e.message);
+    if (process.env.KENSHO_DEBUG) console.error(e.stack);
+    process.exit(2);
+  }
+})();

package/go-helper/go.mod

@@ -0,0 +1,3 @@
+module github.com/kaizenreport/kensho-go-helper
+
+go 1.21

package/go-helper/kensho.go

@@ -0,0 +1,203 @@
+// Package kensho is the Go-side companion to @kaizenreport/kensho-go.
+//
+// It writes structured `KENSHO_META: {...}` lines via t.Logf so the Node CLI
+// (`kensho-go`) can fold first-class steps, attachments, labels, and links
+// into the generated report. This mirrors the helper API exposed by
+// kensho-pytest, kensho-playwright, and the rest of the Kensho adapters.
+//
+// Example:
+//
+//	import (
+//	    "testing"
+//	    kensho "github.com/kaizenreport/kensho-go-helper"
+//	)
+//
+//	func TestLogin(t *testing.T) {
+//	    kensho.Severity(t, "critical")
+//	    kensho.Feature(t, "Authentication")
+//	    kensho.Label(t, "team", "growth")
+//	    kensho.Link(t, "https://jira.example.com/browse/PROJ-123",
+//	        kensho.LinkOpts{Kind: "jira", Label: "PROJ-123"})
+//
+//	    kensho.Step(t, "open the login page", func() {
+//	        // …
+//	    })
+//	    kensho.Attach(t, "/tmp/screenshot.png", kensho.AttachOpts{Kind: "screenshot"})
+//	}
+//
+// The helper writes nothing to stdout — only structured tag lines via t.Logf.
+// All functions are no-ops when t is nil so test utilities can be shared with
+// non-test code without a separate code path.
+package kensho
+
+import (
+	"encoding/json"
+	"fmt"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// LinkOpts carries optional fields for Link.
+type LinkOpts struct {
+	Kind  string // "jira" | "github" | "runbook" | …
+	Label string // human label displayed on the chip
+}
+
+// AttachOpts carries optional fields for Attach.
+type AttachOpts struct {
+	Name     string // override destination filename
+	Kind     string // schema attachment kind override (screenshot, video, log, …)
+	MimeType string // MIME type override
+}
+
+// ParameterOpts carries optional fields for Parameter.
+type ParameterOpts struct {
+	Kind string // "argument" | "context" | "env" | "data-row"
+}
+
+var stepCounter uint64
+
+// Severity records the case severity (blocker | critical | normal | minor | trivial).
+func Severity(t testing.TB, value string) {
+	emit(t, map[string]any{"kind": "severity", "value": value})
+}
+
+// Tag attaches a free-form tag to the case.
+func Tag(t testing.TB, value string) {
+	emit(t, map[string]any{"kind": "tag", "value": value})
+}
+
+// Feature records the behavior feature (e.g. "Authentication").
+func Feature(t testing.TB, value string) {
+	emit(t, map[string]any{"kind": "feature", "value": value})
+}
+
+// Epic records the behavior epic.
+func Epic(t testing.TB, value string) {
+	emit(t, map[string]any{"kind": "epic", "value": value})
+}
+
+// Scenario records the behavior scenario.
+func Scenario(t testing.TB, value string) {
+	emit(t, map[string]any{"kind": "scenario", "value": value})
+}
+
+// Label sets a free-form key/value on the case.
+func Label(t testing.TB, key, value string) {
+	emit(t, map[string]any{"kind": "label", "key": key, "value": value})
+}
+
+// Link attaches a hyperlink (Jira ticket, runbook, PR…) to the case.
+func Link(t testing.TB, url string, opts ...LinkOpts) {
+	rec := map[string]any{"kind": "link", "url": url}
+	if len(opts) > 0 {
+		o := opts[0]
+		if o.Kind != "" {
+			rec["linkKind"] = o.Kind
+		}
+		if o.Label != "" {
+			rec["label"] = o.Label
+		}
+	}
+	emit(t, rec)
+}
+
+// Parameter records a test parameter (e.g. table-driven inputs).
+func Parameter(t testing.TB, name, value string, opts ...ParameterOpts) {
+	rec := map[string]any{"kind": "parameter", "name": name, "value": value}
+	if len(opts) > 0 && opts[0].Kind != "" {
+		rec["paramKind"] = opts[0].Kind
+	}
+	emit(t, rec)
+}
+
+// Attach registers a file to be copied into kensho-results/attachments/<caseId>/
+// at conversion time. The file path must exist on disk when `kensho-go` runs.
+func Attach(t testing.TB, path string, opts ...AttachOpts) {
+	rec := map[string]any{"kind": "attach", "path": path}
+	if len(opts) > 0 {
+		o := opts[0]
+		if o.Name != "" {
+			rec["name"] = o.Name
+		}
+		if o.Kind != "" {
+			rec["kind"] = "attach" // keep schema kind in attach-record below
+			rec["attachKind"] = o.Kind
+		}
+		if o.MimeType != "" {
+			rec["mimeType"] = o.MimeType
+		}
+	}
+	// The Node CLI reads `kind: attach` and falls back to a sensible default
+	// for the on-disk attachment kind; AttachOpts.Kind is forwarded as
+	// `attachKind` so we can keep the meta envelope's `kind` discriminator
+	// stable.
+	emit(t, rec)
+}
+
+// Step opens a Kensho step around fn. Steps may be nested by calling Step
+// inside fn. If fn panics or marks the test as failed, the step is recorded
+// with status `fail`.
+func Step(t testing.TB, title string, fn func()) {
+	if t == nil {
+		if fn != nil {
+			fn()
+		}
+		return
+	}
+	id := fmt.Sprintf("s%d", atomic.AddUint64(&stepCounter, 1))
+	emit(t, map[string]any{
+		"kind":  "step_start",
+		"id":    id,
+		"title": title,
+		"t":     time.Now().UnixMilli(),
+	})
+
+	status := "pass"
+	failed := false
+	defer func() {
+		if r := recover(); r != nil {
+			status = "fail"
+			emit(t, map[string]any{
+				"kind":   "step_end",
+				"id":     id,
+				"status": status,
+				"t":      time.Now().UnixMilli(),
+			})
+			panic(r)
+		}
+		if failed || t.Failed() {
+			status = "fail"
+		}
+		emit(t, map[string]any{
+			"kind":   "step_end",
+			"id":     id,
+			"status": status,
+			"t":      time.Now().UnixMilli(),
+		})
+	}()
+
+	if fn != nil {
+		fn()
+	}
+	if t.Failed() {
+		failed = true
+	}
+}
+
+// emit writes the meta record. We use t.Logf so it's interleaved with the
+// surrounding test output; the Node CLI parses any line starting with
+// "KENSHO_META:" out of the captured stream.
+func emit(t testing.TB, rec map[string]any) {
+	if t == nil {
+		return
+	}
+	b, err := json.Marshal(rec)
+	if err != nil {
+		return
+	}
+	t.Helper()
+	// Newline is added by t.Logf; the prefix is what the converter looks for.
+	t.Logf("KENSHO_META: %s", string(b))
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kaizenreport/kensho-go",
+  "version": "0.1.0",
+  "description": "Convert `go test -json` output into a kensho-results/ bundle so the Kensho CLI can render a rich HTML report.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "kensho-go": "./bin/kensho-go.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "go-helper",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kaizenreport/kensho-schema": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandon1794/kensho.git",
+    "directory": "packages/go"
+  },
+  "homepage": "https://github.com/brandon1794/kensho/tree/main/packages/go#readme",
+  "bugs": {
+    "url": "https://github.com/brandon1794/kensho/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,628 @@
+// @kaizenreport/kensho-go — convert `go test -json` output into a
+// kensho-results/ bundle. Pure stdlib JS, no deps beyond the schema.
+//
+// `go test -json` emits one JSON object per line, with these Actions we care
+// about:
+//
+//   run     — a test (or sub-test) started.
+//   output  — captured stdout/stderr line for that test.
+//   pass    — the test finished successfully.
+//   fail    — the test finished with at least one assertion failure or panic.
+//   skip    — the test was skipped (t.Skip / build-tag).
+//   pause / cont — t.Parallel sequencing; we ignore for case timing.
+//
+// We bucket events by (Package, Test). Top-level tests become Kensho cases.
+// Sub-tests created with `t.Run("sub", ...)` become children of their parent;
+// by default each sub-test is its own Kensho case (so the dashboard sees the
+// full table-driven matrix), but the caller can opt into folding them into
+// child steps with `--subtests=children`.
+//
+// A test that emits a Go panic (`panic:` in its captured output) is mapped
+// to Kensho `fail` — Go's std test runner has no `broken` concept, so the
+// schema's "infrastructure failure" bucket is reserved for things like
+// missing input files at the converter layer.
+//
+// Helper hooks: tests using the optional `kensho` Go module write structured
+// records via t.Logf as `KENSHO_META: <json>` lines. We parse those out so
+// users get first-class steps, attachments, labels and links matching the
+// other adapters.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, basename, extname, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { emptyRun, computeTotals, stableCaseId, validateRun, envInfo } from '@kaizenreport/kensho-schema';
+
+const SEVERITY_NAMES = ['blocker', 'critical', 'normal', 'minor', 'trivial'];
+
+const MIME_BY_EXT = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp', '.webm': 'video/webm', '.mp4': 'video/mp4',
+  '.zip': 'application/zip', '.html': 'text/html',
+  '.json': 'application/json', '.txt': 'text/plain', '.log': 'text/plain',
+  '.har': 'application/json',
+};
+
+const KIND_BY_EXT = {
+  '.png': 'screenshot', '.jpg': 'screenshot', '.jpeg': 'screenshot', '.webp': 'screenshot',
+  '.webm': 'video', '.mp4': 'video',
+  '.zip': 'trace',
+  '.html': 'html', '.json': 'json', '.txt': 'text', '.log': 'log',
+  '.har': 'har',
+};
+
+// envInfo() is imported from @kaizenreport/kensho-schema below.
+
+// --- input ingestion ---------------------------------------------------------
+
+function parseLines(text) {
+  const events = [];
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line[0] !== '{') continue; // tolerate stray tool output before/after the stream
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Ignore malformed lines — `go test -json` very occasionally emits build
+      // diagnostics on stderr that get tee'd in.
+    }
+  }
+  return events;
+}
+
+export function readEvents(input) {
+  if (input == null) return [];
+  if (Array.isArray(input)) return input.flatMap(p => parseLines(readFileSync(p, 'utf8')));
+  return parseLines(readFileSync(input, 'utf8'));
+}
+
+export async function readEventsFromStream(stream) {
+  return new Promise((res, rej) => {
+    const chunks = [];
+    stream.on('data', c => chunks.push(c));
+    stream.on('end', () => res(parseLines(Buffer.concat(chunks).toString('utf8'))));
+    stream.on('error', rej);
+  });
+}
+
+// --- helper meta protocol ----------------------------------------------------
+//
+// The optional Go helper writes `KENSHO_META: <json>` lines via t.Logf.
+// Each meta record carries a `kind` so we know how to fold it into the case.
+// Recognised kinds:
+//
+//   step_start    { id, title, action?, parent?, t }
+//   step_end      { id, status, t }
+//   attach        { name, path, kind?, mimeType?, stepId? }
+//   label         { key, value }
+//   link          { url, kind?, label? }
+//   severity      { value }
+//   tag           { value }
+//   feature/epic/scenario  { value }
+//   parameter     { name, value, kind? }
+
+const META_PREFIX = 'KENSHO_META:';
+
+function parseMeta(line) {
+  const idx = line.indexOf(META_PREFIX);
+  if (idx < 0) return null;
+  const json = line.slice(idx + META_PREFIX.length).trim();
+  if (!json.startsWith('{')) return null;
+  try {
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+// --- core conversion ---------------------------------------------------------
+
+function severityFromName(name) {
+  // Recognise the conventions documented in the README:
+  //   Test_blocker_*, Test_critical_*, Test_normal_*, Test_minor_*, Test_trivial_*
+  //   …or sub-tests named e.g. "severity:critical" / "@critical".
+  const lower = String(name || '').toLowerCase();
+  for (const sev of SEVERITY_NAMES) {
+    if (new RegExp(`(?:^|[^a-z])${sev}(?:$|[^a-z])`).test(lower)) return sev;
+  }
+  return undefined;
+}
+
+function extractTags(name) {
+  const tags = [];
+  const re = /@([\w-]+)/g;
+  let m;
+  while ((m = re.exec(String(name || '')))) tags.push(m[1]);
+  return tags;
+}
+
+function packagePathToFile(pkg, file) {
+  // `Package` is the import path (e.g. github.com/foo/bar/internal). When the
+  // helper meta isn't present we don't know the precise file, so we synthesise
+  // a stable path from the import path so stableCaseId is consistent across
+  // runs without coupling to the user's $GOPATH.
+  if (file) return file;
+  if (!pkg) return undefined;
+  return pkg.split('/').join('/') + '/*_test.go';
+}
+
+function safeIso(t) {
+  if (!t) return undefined;
+  const d = new Date(t);
+  if (Number.isNaN(d.getTime())) return undefined;
+  return d.toISOString();
+}
+
+function splitTestPath(test) {
+  // Go convention: parent test and sub-tests joined by "/"
+  return String(test || '').split('/');
+}
+
+function fileHash(p) {
+  try {
+    const h = createHash('sha256');
+    h.update(statSync(p).size + ':' + p);
+    return h.digest('hex').slice(0, 16);
+  } catch { return undefined; }
+}
+
+function shortId(prefix) {
+  return prefix + '_' + randomUUID().replace(/-/g, '').slice(0, 10);
+}
+
+/**
+ * Convert a stream of `go test -json` events into a kensho-results/ bundle.
+ *
+ * @param {{
+ *   events: object[],
+ *   output: string,
+ *   project?: { name?: string, slug?: string, url?: string },
+ *   runId?: string,
+ *   subtests?: 'cases' | 'children',
+ * }} opts
+ */
+export function convertGoEvents(opts) {
+  const events = opts.events || [];
+  const outDir = resolve(process.cwd(), opts.output || 'kensho-results');
+  const casesDir = resolve(outDir, 'cases');
+  const attachmentsDir = resolve(outDir, 'attachments');
+  mkdirSync(outDir, { recursive: true });
+  mkdirSync(casesDir, { recursive: true });
+  mkdirSync(attachmentsDir, { recursive: true });
+
+  const subtests = opts.subtests === 'children' ? 'children' : 'cases';
+  const startedAt = new Date().toISOString();
+
+  // Two-pass: first build per-(pkg,test) buckets, then flatten into cases
+  // honoring the sub-test mode.
+  /** @type {Map<string, {
+   *   pkg: string,
+   *   test: string,
+   *   parts: string[],
+   *   startedAt?: string,
+   *   finishedAt?: string,
+   *   elapsed?: number,
+   *   status?: string,
+   *   panic?: boolean,
+   *   output: string[],
+   *   meta: object[],
+   *   parentKey?: string,
+   * }>} */
+  const buckets = new Map();
+  const orderedKeys = [];
+
+  const keyFor = (pkg, test) => `${pkg}::${test}`;
+
+  for (const ev of events) {
+    if (!ev || !ev.Action) continue;
+    if (!ev.Test) continue; // package-level pass/fail/output — ignore for case building
+    const key = keyFor(ev.Package || '', ev.Test);
+    let b = buckets.get(key);
+    if (!b) {
+      const parts = splitTestPath(ev.Test);
+      const parentKey = parts.length > 1 ? keyFor(ev.Package || '', parts.slice(0, -1).join('/')) : undefined;
+      b = {
+        pkg: ev.Package || '',
+        test: ev.Test,
+        parts,
+        output: [],
+        meta: [],
+        parentKey,
+      };
+      buckets.set(key, b);
+      orderedKeys.push(key);
+    }
+    switch (ev.Action) {
+      case 'run':
+        b.startedAt = safeIso(ev.Time) || b.startedAt;
+        break;
+      case 'output': {
+        const txt = String(ev.Output || '');
+        const meta = parseMeta(txt);
+        if (meta) b.meta.push(meta);
+        else if (txt.length) b.output.push(txt.replace(/\n$/, ''));
+        if (/^\s*panic:/m.test(txt)) b.panic = true;
+        break;
+      }
+      case 'pass':
+      case 'fail':
+      case 'skip':
+        b.status = ev.Action;
+        b.finishedAt = safeIso(ev.Time) || b.finishedAt;
+        if (typeof ev.Elapsed === 'number') b.elapsed = ev.Elapsed;
+        break;
+      // pause / cont / bench — ignored
+    }
+  }
+
+  const usedIds = new Set();
+  /** @type {object[]} */
+  const cases = [];
+
+  for (const key of orderedKeys) {
+    const b = buckets.get(key);
+    if (!b) continue;
+    const isSub = b.parts.length > 1;
+    if (subtests === 'children' && isSub) continue; // handled by the parent
+
+    const caseObj = bucketToCase(b, buckets, subtests, usedIds);
+    // Materialise attachments declared via meta into the on-disk attachments
+    // dir so the bundle is self-contained — must happen before we write the
+    // case JSON so the attachment records are present.
+    materialiseAttachments(caseObj, attachmentsDir, outDir);
+    cases.push(caseObj);
+    writeFileSync(resolve(casesDir, caseObj.id + '.json'), JSON.stringify(caseObj, null, 2));
+  }
+
+  const finishedAt = new Date().toISOString();
+  const run = emptyRun({
+    id: opts.runId || ('run_' + new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14)),
+    project: {
+      name: opts.project?.name || 'Unknown project',
+      slug: opts.project?.slug || 'unknown',
+      url: opts.project?.url,
+    },
+    framework: { name: 'go-test', version: '0.1.0' },
+    env: envInfo(),
+    startedAt,
+  });
+  run.finishedAt = finishedAt;
+  run.durationMs = Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt));
+  run.testCases = cases;
+  run.totals = computeTotals(cases);
+
+  writeFileSync(resolve(outDir, 'run.json'), JSON.stringify(run, null, 2));
+  const { ok, errors } = validateRun(run);
+  if (!ok) {
+    console.warn('[kensho-go] run.json failed validation:');
+    for (const e of errors.slice(0, 8)) console.warn('  -', e);
+  }
+  console.log(`[kensho-go] wrote ${cases.length} cases + run.json to ${outDir}`);
+  return { outputDir: outDir, cases: cases.length, valid: ok };
+}
+
+function bucketToCase(b, buckets, subtests, usedIds) {
+  const fullName = `${b.pkg}::${b.test}`;
+  const filePath = packagePathToFile(b.pkg);
+  let id = stableCaseId(fullName, filePath);
+  if (usedIds.has(id)) {
+    let i = 2;
+    while (usedIds.has(id + '_' + i)) i++;
+    id = id + '_' + i;
+  }
+  usedIds.add(id);
+
+  const suite = b.pkg ? b.pkg.split('/').filter(Boolean) : [];
+  const tags = Array.from(new Set([...extractTags(b.test), ...metaTags(b.meta)]));
+
+  const status = mapStatus(b);
+  const startedAt = b.startedAt || new Date().toISOString();
+  const duration = Math.max(0, Math.round((b.elapsed || 0) * 1000));
+  const finishedAt = b.finishedAt || new Date(Date.parse(startedAt) + duration).toISOString();
+
+  const errors = collectErrors(b);
+  const logs = collectLogs(b, startedAt);
+  const labels = metaLabels(b.meta);
+  const links = metaLinks(b.meta);
+  const parameters = metaParameters(b.meta);
+  const behavior = metaBehavior(b.meta);
+  const severity = metaSeverity(b.meta) || severityFromName(lastPart(b.test));
+
+  let steps = metaSteps(b.meta);
+
+  // Collect attach meta — the actual file copy happens in
+  // materialiseAttachments after the case object is in hand.
+  const attachMeta = b.meta.filter(m => m && m.kind === 'attach' && m.path);
+
+  // When sub-tests are folded into children, build a synthetic step tree
+  // from each sub-bucket and append it to this case's `steps`.
+  if (subtests === 'children') {
+    const childKeys = Array.from(buckets.keys()).filter(k => {
+      const cb = buckets.get(k);
+      return cb && cb.parentKey === keyFor(b.pkg, b.test) && cb.parts.length === b.parts.length + 1;
+    });
+    childKeys.sort();
+    for (const childKey of childKeys) {
+      const cb = buckets.get(childKey);
+      const childStep = subBucketToStep(cb, buckets, b.startedAt || startedAt);
+      if (childStep) steps.push(childStep);
+    }
+  }
+
+  const caseObj = {
+    id,
+    name: lastPart(b.test),
+    fullName,
+    filePath,
+    suite,
+    tags,
+    status,
+    startedAt,
+    finishedAt,
+    duration,
+    retries: 0,
+    platform: process.platform,
+  };
+  if (severity) caseObj.severity = severity;
+  if (Object.keys(behavior).length) caseObj.behavior = behavior;
+  if (Object.keys(labels).length) caseObj.labels = labels;
+  if (links.length) caseObj.links = links;
+  if (parameters.length) caseObj.parameters = parameters;
+  if (steps.length) caseObj.steps = steps;
+  if (errors.length) caseObj.errors = errors;
+  if (logs.length) caseObj.logs = logs;
+  if (attachMeta.length) caseObj._attachMeta = attachMeta;
+  return caseObj;
+}
+
+function subBucketToStep(b, buckets, parentStartedAt) {
+  if (!b) return null;
+  const startedAt = b.startedAt || parentStartedAt || new Date().toISOString();
+  const duration = Math.max(0, Math.round((b.elapsed || 0) * 1000));
+  const status = mapStatus(b);
+  const stepStatus = status === 'broken' ? 'fail' : status; // step enum has no 'broken'
+  const step = {
+    id: shortId('step'),
+    title: lastPart(b.test),
+    status: stepStatus,
+    startedAt,
+    duration,
+    phase: 'body',
+  };
+  // recurse into deeper sub-tests
+  const childKeys = Array.from(buckets.keys()).filter(k => {
+    const cb = buckets.get(k);
+    return cb && cb.parentKey === keyFor(b.pkg, b.test) && cb.parts.length === b.parts.length + 1;
+  });
+  if (childKeys.length) {
+    step.children = [];
+    for (const ck of childKeys.sort()) {
+      const child = subBucketToStep(buckets.get(ck), buckets, startedAt);
+      if (child) step.children.push(child);
+    }
+  }
+  // Capture failure output as an assertion stack so the viewer renders it.
+  if (status === 'fail') {
+    const stack = b.output.join('\n').trim();
+    if (stack) step.assertion = { stack };
+  }
+  return step;
+}
+
+function keyFor(pkg, test) { return `${pkg}::${test}`; }
+
+function lastPart(test) {
+  const parts = splitTestPath(test);
+  return parts[parts.length - 1];
+}
+
+function mapStatus(b) {
+  if (b.panic && b.status !== 'pass') return 'fail';
+  if (b.status === 'pass') return 'pass';
+  if (b.status === 'fail') return 'fail';
+  if (b.status === 'skip') return 'skip';
+  // No terminal action recorded — likely a build failure or interrupted run.
+  return 'broken';
+}
+
+function collectErrors(b) {
+  if (b.status !== 'fail' && !b.panic) return [];
+  const text = b.output.join('\n');
+  // First, look for a panic stanza — `panic: <message>` followed by goroutine
+  // frames is the canonical Go panic shape.
+  const panicMatch = /^\s*panic:\s*(.*)$/m.exec(text);
+  if (panicMatch) {
+    return [{
+      message: panicMatch[1].trim() || 'panic',
+      stack: text.trim(),
+      type: 'panic',
+    }];
+  }
+  // Otherwise pull the first `--- FAIL: …` block plus the surrounding lines.
+  const failRe = /^\s*([\w./_-]+\.go:\d+):\s*(.*)$/m;
+  const m = failRe.exec(text);
+  if (m) {
+    return [{
+      message: m[2].trim() || 'test failed',
+      stack: text.trim(),
+    }];
+  }
+  // Fallback — first non-empty line.
+  const first = text.split(/\n/).map(s => s.trim()).find(Boolean);
+  return [{
+    message: first || 'test failed',
+    stack: text.trim() || undefined,
+  }];
+}
+
+function collectLogs(b, startedAt) {
+  const logs = [];
+  const baseMs = Date.parse(startedAt);
+  let i = 0;
+  for (const line of b.output) {
+    const trimmed = line.replace(/\s+$/, '');
+    if (!trimmed) continue;
+    if (trimmed.startsWith(META_PREFIX)) continue;
+    // Skip the structural `=== RUN`, `--- PASS`, `--- FAIL` lines — they're
+    // noise for the report viewer (the case status/duration already capture
+    // that information).
+    if (/^\s*===\s+(RUN|PAUSE|CONT|NAME)/.test(trimmed)) continue;
+    if (/^\s*---\s+(PASS|FAIL|SKIP)/.test(trimmed)) continue;
+    if (/^\s*PASS\s*$/.test(trimmed)) continue;
+    if (/^\s*FAIL\s*$/.test(trimmed)) continue;
+    if (/^\s*ok\s+\S+\s+\S+\s*$/.test(trimmed)) continue;
+    const level = /panic|error|FAIL/i.test(trimmed) ? 'error'
+      : /warn/i.test(trimmed) ? 'warn'
+      : 'info';
+    logs.push({ t: Math.max(0, i++), level, msg: trimmed });
+  }
+  return logs;
+}
+
+function metaTags(meta) {
+  return meta.filter(m => m && m.kind === 'tag' && m.value).map(m => String(m.value));
+}
+
+function metaLabels(meta) {
+  const out = {};
+  for (const m of meta) {
+    if (m && m.kind === 'label' && m.key) out[String(m.key)] = String(m.value ?? '');
+  }
+  return out;
+}
+
+function metaLinks(meta) {
+  const out = [];
+  for (const m of meta) {
+    if (m && m.kind === 'link' && m.url) {
+      const link = { url: String(m.url) };
+      if (m.linkKind) link.kind = String(m.linkKind);
+      if (m.label) link.label = String(m.label);
+      out.push(link);
+    }
+  }
+  return out;
+}
+
+function metaParameters(meta) {
+  return meta
+    .filter(m => m && m.kind === 'parameter' && m.name)
+    .map(m => ({
+      name: String(m.name),
+      value: String(m.value ?? ''),
+      ...(m.paramKind ? { kind: String(m.paramKind) } : {}),
+    }));
+}
+
+function metaBehavior(meta) {
+  const out = {};
+  for (const m of meta) {
+    if (!m || !m.value) continue;
+    if (m.kind === 'feature') out.feature = String(m.value);
+    else if (m.kind === 'epic') out.epic = String(m.value);
+    else if (m.kind === 'scenario' || m.kind === 'story') out.scenario = String(m.value);
+  }
+  return out;
+}
+
+function metaSeverity(meta) {
+  for (const m of meta) {
+    if (m && m.kind === 'severity' && m.value) {
+      const v = String(m.value).toLowerCase();
+      if (SEVERITY_NAMES.includes(v)) return v;
+    }
+  }
+  return undefined;
+}
+
+function metaSteps(meta) {
+  // Build the step tree from interleaved step_start / step_end records.
+  // `id` strings are user-supplied so we use them as the join key; if a
+  // user forgets to call `step_end`, the unmatched step is left as `pass`
+  // (no duration available).
+  const open = []; // stack of open steps (innermost last)
+  const roots = [];
+  for (const m of meta) {
+    if (!m) continue;
+    if (m.kind === 'step_start') {
+      const step = {
+        id: m.id ? `step_${String(m.id)}` : shortId('step'),
+        _userId: m.id,
+        title: String(m.title || 'step'),
+        status: 'pass',
+        startedAt: safeIso(m.t) || new Date().toISOString(),
+        duration: 0,
+        phase: 'body',
+        _startedMs: typeof m.t === 'number' ? m.t : Date.parse(safeIso(m.t) || new Date().toISOString()),
+      };
+      if (m.action) step.action = String(m.action);
+      const parent = open[open.length - 1];
+      if (parent) (parent.children ||= []).push(step);
+      else roots.push(step);
+      open.push(step);
+    } else if (m.kind === 'step_end') {
+      // close the matching step (by id or topmost)
+      let idx = -1;
+      if (m.id) {
+        for (let i = open.length - 1; i >= 0; i--) {
+          if (open[i]._userId === m.id) { idx = i; break; }
+        }
+      }
+      if (idx === -1) idx = open.length - 1;
+      if (idx === -1) continue;
+      const step = open.splice(idx, 1)[0];
+      if (m.status && (m.status === 'pass' || m.status === 'fail' || m.status === 'skip')) {
+        step.status = m.status;
+      }
+      const endMs = typeof m.t === 'number' ? m.t : Date.parse(safeIso(m.t) || new Date().toISOString());
+      step.duration = Math.max(0, Math.round(endMs - (step._startedMs || endMs)));
+      delete step._startedMs;
+      delete step._userId;
+    }
+  }
+  // Force-close any leaks — we never want a partial step to leave dangling
+  // _internal fields in the output JSON.
+  for (const step of open) {
+    delete step._startedMs;
+    delete step._userId;
+  }
+  // Strip helpers from nested children too.
+  const strip = (s) => {
+    if (!s) return;
+    delete s._startedMs;
+    delete s._userId;
+    (s.children || []).forEach(strip);
+  };
+  roots.forEach(strip);
+  return roots;
+}
+
+function materialiseAttachments(caseObj, attachmentsRoot, outDir) {
+  // The Go helper uses meta with kind "attach" — we copy the file into the
+  // bundle so the report directory is self-contained.
+  if (!Array.isArray(caseObj._attachMeta)) return;
+  for (const att of caseObj._attachMeta) {
+    if (!att.path) continue;
+    const src = isAbsolute(att.path) ? att.path : resolve(process.cwd(), att.path);
+    if (!existsSync(src)) continue;
+    const destDir = resolve(attachmentsRoot, caseObj.id);
+    mkdirSync(destDir, { recursive: true });
+    const ext = extname(src).toLowerCase();
+    const attId = shortId('att');
+    const destName = `${attId}_${att.name || basename(src)}`;
+    const dest = resolve(destDir, destName);
+    try { copyFileSync(src, dest); } catch { continue; }
+    const rec = {
+      id: attId,
+      kind: att.kind || KIND_BY_EXT[ext] || 'text',
+      relativePath: dest.slice(outDir.length).replace(/^[\/\\]/, ''),
+      mimeType: att.mimeType || MIME_BY_EXT[ext] || 'application/octet-stream',
+    };
+    const sz = (() => { try { return statSync(dest).size; } catch { return undefined; } })();
+    if (sz !== undefined) rec.sizeBytes = sz;
+    const sha = fileHash(dest);
+    if (sha) rec.sha256 = sha;
+    (caseObj.attachments ||= []).push(rec);
+  }
+  delete caseObj._attachMeta;
+}