@reventlessdev/reventless-gwt 1.0.0-alpha.100

package/src/OutboundTranslation_GWT.res

@@ -0,0 +1,238 @@
+open ReventlessCore
+
+// Minimal inline spec for OutboundTranslationSlice. `translate` is async and
+// supplied at test-time via `whenTranslateMocked` so the external service is
+// never hit. The spec's own `translate` is not part of the GWT — it's
+// exercised only through the runtime tests.
+module type SliceSpec = {
+  let name: string
+
+  @schema
+  type consumedEvent
+
+  @schema
+  type outboundItem
+
+  @schema
+  type inboundCommand
+
+  let collect: consumedEvent => array<(string, outboundItem)>
+}
+
+// Status enum reflecting how the slice's runtime labels a TODO after a
+// translate call. A successful translate (Ok) marks the item #Completed;
+// a failure (Error) leaves it #Pending for retry up to `maxRetries`.
+type todoStatus = [#Completed | #Pending]
+
+module type T = {
+  module Spec: SliceSpec
+
+  let describe: (string, unit => unit) => unit
+  let test: (string, ~timeout: int=?, unit => promise<Outcome.outcome>) => unit
+  // Sync companion for the `collect` leg, whose combinators return
+  // `Outcome.outcome` directly (no Promise). The async `test` works for
+  // collect bodies too, but only after a manual `Promise.resolve` wrapper.
+  let testSync: (string, unit => Outcome.outcome) => unit
+
+  type translateResult =
+    result<option<(string, Spec.inboundCommand)>, string>
+
+  // The state the pipeline carries after a translate attempt. `retries` counts
+  // the number of failed re-attempts (0 for a single `whenTranslateMocked`).
+  type attempt = {
+    id: string,
+    item: Spec.outboundItem,
+    result: translateResult,
+    retries: int,
+  }
+
+  // Unit — collect
+  let givenEvent: Spec.consumedEvent => Spec.consumedEvent
+  let whenCollect: Spec.consumedEvent => array<(string, Spec.outboundItem)>
+  let thenTodos: (
+    array<(string, Spec.outboundItem)>,
+    array<(string, Spec.outboundItem)>,
+  ) => Outcome.outcome
+
+  // Unit — translate
+  let givenTodo: (string, Spec.outboundItem) => (string, Spec.outboundItem)
+  let whenTranslateMocked: (
+    (string, Spec.outboundItem),
+    (string, Spec.outboundItem) => promise<translateResult>,
+  ) => promise<attempt>
+  // Re-invokes the mock on each `Error` up to `maxRetries` times (or until it
+  // returns `Ok`), tracking how many retries were spent — the real counter
+  // `thenRetryRecorded` asserts against.
+  let whenTranslateRetrying: (
+    (string, Spec.outboundItem),
+    ~maxRetries: int,
+    (string, Spec.outboundItem) => promise<translateResult>,
+  ) => promise<attempt>
+  let thenCommand: (
+    promise<attempt>,
+    string,
+    Spec.inboundCommand,
+  ) => promise<Outcome.outcome>
+  let thenNoCommand: promise<attempt> => promise<Outcome.outcome>
+  let thenRetryRecorded: (promise<attempt>, int) => promise<Outcome.outcome>
+  let thenTodoStatus: (promise<attempt>, string, todoStatus) => promise<Outcome.outcome>
+}
+
+module Make = (Spec: SliceSpec): (T with module Spec = Spec) => {
+  module Spec = Spec
+
+  S.enableJson()
+
+  let describe = JestBind.describe
+  let test = (name, ~timeout=?, body) =>
+    JestBind.testPromise(~slice=Spec.name, name, ~timeout?, body)
+  let testSync = (name, body) => JestBind.test(~slice=Spec.name, name, body)
+
+  type translateResult =
+    result<option<(string, Spec.inboundCommand)>, string>
+
+  type attempt = {
+    id: string,
+    item: Spec.outboundItem,
+    result: translateResult,
+    retries: int,
+  }
+
+  let encItem = (i: Spec.outboundItem) => i->Message.encode(Spec.outboundItemSchema)
+  let encItems = (arr: array<(string, Spec.outboundItem)>) =>
+    arr->Array.map(((id, i)) => (id, encItem(i)))
+  let encInbound = (c: Spec.inboundCommand) =>
+    c->Message.encode(Spec.inboundCommandSchema)
+
+  // Unit: collect
+  let givenEvent = e => e
+  let whenCollect = e => e->Spec.collect
+  let thenTodos = (actual, expected) =>
+    if actual == expected {
+      Outcome.pass
+    } else {
+      Outcome.fail(
+        TodoMismatch({
+          expected: encItems(expected),
+          actual: encItems(actual),
+        }),
+      )
+    }
+
+  // Unit: translate
+  let givenTodo = (id, item) => (id, item)
+  let whenTranslateMocked = async ((id, item), mock) => {
+    let result = await mock(id, item)
+    {id, item, result, retries: 0}
+  }
+
+  let whenTranslateRetrying = async ((id, item), ~maxRetries, mock) => {
+    let result = ref(await mock(id, item))
+    let retries = ref(0)
+    let failed = () =>
+      switch result.contents {
+      | Error(_) => true
+      | Ok(_) => false
+      }
+    while failed() && retries.contents < maxRetries {
+      retries := retries.contents + 1
+      result := await mock(id, item)
+    }
+    {id, item, result: result.contents, retries: retries.contents}
+  }
+
+  let commandPairJson = (id, cmd) => {
+    let d = Dict.make()
+    d->Dict.set("id", JSON.Encode.string(id))
+    d->Dict.set("command", encInbound(cmd))
+    JSON.Encode.object(d)
+  }
+
+  let thenCommand = async (pending, expectedId, expectedCmd) => {
+    let {result, _} = await pending
+    switch result {
+    | Ok(Some((id, cmd))) if id == expectedId && cmd == expectedCmd => Outcome.pass
+    | Ok(Some((id, cmd))) =>
+      Outcome.fail(
+        EventsMismatch({
+          expected: [commandPairJson(expectedId, expectedCmd)],
+          actual: [commandPairJson(id, cmd)],
+        }),
+      )
+    | Ok(None) =>
+      Outcome.fail(
+        EventsMismatch({
+          expected: [commandPairJson(expectedId, expectedCmd)],
+          actual: [],
+        }),
+      )
+    | Error(msg) =>
+      Outcome.fail(
+        TranslateError({expected: "(command)", actual: Some(msg)}),
+      )
+    }
+  }
+
+  let thenNoCommand = async pending => {
+    let {result, _} = await pending
+    switch result {
+    | Ok(None) => Outcome.pass
+    | Ok(Some((id, cmd))) =>
+      Outcome.fail(NoEventExpected({actual: [commandPairJson(id, cmd)]}))
+    | Error(msg) =>
+      Outcome.fail(
+        TranslateError({expected: "(no command)", actual: Some(msg)}),
+      )
+    }
+  }
+
+  // `thenRetryRecorded(n)` — asserts the harness spent exactly `n` retries.
+  // Pair with `whenTranslateRetrying(~maxRetries)`, which re-invokes the mock on
+  // each failure and tracks the count; a single `whenTranslateMocked` records 0.
+  let thenRetryRecorded = async (pending, expectedRetries) => {
+    let {retries, _} = await pending
+    if retries == expectedRetries {
+      Outcome.pass
+    } else {
+      Outcome.fail(
+        StateMismatch({
+          key: "retries",
+          expected: Some(JSON.Encode.int(expectedRetries)),
+          actual: Some(JSON.Encode.int(retries)),
+        }),
+      )
+    }
+  }
+
+  let statusToString = (s: todoStatus) =>
+    switch s {
+    | #Completed => "#Completed"
+    | #Pending => "#Pending"
+    }
+
+  let thenTodoStatus = async (pending, expectedId, expectedStatus) => {
+    let {id, result, _} = await pending
+    let actualStatus: todoStatus =
+      switch result {
+      | Ok(_) => #Completed
+      | Error(_) => #Pending
+      }
+    if id == expectedId && actualStatus == expectedStatus {
+      Outcome.pass
+    } else {
+      let encOne = (rid, rstatus) => {
+        let d = Dict.make()
+        d->Dict.set("id", JSON.Encode.string(rid))
+        d->Dict.set("status", JSON.Encode.string(statusToString(rstatus)))
+        JSON.Encode.object(d)
+      }
+      Outcome.fail(
+        StateMismatch({
+          key: id,
+          expected: Some(encOne(expectedId, expectedStatus)),
+          actual: Some(encOne(id, actualStatus)),
+        }),
+      )
+    }
+  }
+}

package/src/OutboundTranslation_GWT.res.mjs

@@ -0,0 +1,186 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Outcome$ReventlessGwt from "./Outcome.res.mjs";
+import * as JestBind$ReventlessGwt from "./JestBind.res.mjs";
+import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
+
+function Make(Spec) {
+  S.enableJson();
+  let test = (name, timeout, body) => JestBind$ReventlessGwt.testPromise(Spec.name, name, timeout, body);
+  let testSync = (name, body) => JestBind$ReventlessGwt.test(Spec.name, name, body);
+  let encItems = arr => arr.map(param => [
+    param[0],
+    Message$ReventlessCore.encode(param[1], Spec.outboundItemSchema)
+  ]);
+  let givenEvent = e => e;
+  let whenCollect = e => Spec.collect(e);
+  let thenTodos = (actual, expected) => {
+    if (Primitive_object.equal(actual, expected)) {
+      return Outcome$ReventlessGwt.pass;
+    } else {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TodoMismatch",
+        expected: encItems(expected),
+        actual: encItems(actual)
+      });
+    }
+  };
+  let givenTodo = (id, item) => [
+    id,
+    item
+  ];
+  let whenTranslateMocked = async (param, mock) => {
+    let item = param[1];
+    let id = param[0];
+    let result = await mock(id, item);
+    return {
+      id: id,
+      item: item,
+      result: result,
+      retries: 0
+    };
+  };
+  let whenTranslateRetrying = async (param, maxRetries, mock) => {
+    let item = param[1];
+    let id = param[0];
+    let result = {
+      contents: await mock(id, item)
+    };
+    let retries = 0;
+    let failed = () => {
+      let match = result.contents;
+      return match.TAG !== "Ok";
+    };
+    while (failed() && retries < maxRetries) {
+      retries = retries + 1 | 0;
+      result.contents = await mock(id, item);
+    };
+    return {
+      id: id,
+      item: item,
+      result: result.contents,
+      retries: retries
+    };
+  };
+  let commandPairJson = (id, cmd) => {
+    let d = {};
+    d["id"] = id;
+    d["command"] = Message$ReventlessCore.encode(cmd, Spec.inboundCommandSchema);
+    return d;
+  };
+  let thenCommand = async (pending, expectedId, expectedCmd) => {
+    let match = await pending;
+    let result = match.result;
+    if (result.TAG !== "Ok") {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TranslateError",
+        expected: "(command)",
+        actual: result._0
+      });
+    }
+    let match$1 = result._0;
+    if (match$1 === undefined) {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "EventsMismatch",
+        expected: [commandPairJson(expectedId, expectedCmd)],
+        actual: []
+      });
+    }
+    let cmd = match$1[1];
+    let id = match$1[0];
+    if (id === expectedId && Primitive_object.equal(cmd, expectedCmd)) {
+      return Outcome$ReventlessGwt.pass;
+    } else {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "EventsMismatch",
+        expected: [commandPairJson(expectedId, expectedCmd)],
+        actual: [commandPairJson(id, cmd)]
+      });
+    }
+  };
+  let thenNoCommand = async pending => {
+    let match = await pending;
+    let result = match.result;
+    if (result.TAG !== "Ok") {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TranslateError",
+        expected: "(no command)",
+        actual: result._0
+      });
+    }
+    let match$1 = result._0;
+    if (match$1 !== undefined) {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "NoEventExpected",
+        actual: [commandPairJson(match$1[0], match$1[1])]
+      });
+    } else {
+      return Outcome$ReventlessGwt.pass;
+    }
+  };
+  let thenRetryRecorded = async (pending, expectedRetries) => {
+    let match = await pending;
+    let retries = match.retries;
+    if (retries === expectedRetries) {
+      return Outcome$ReventlessGwt.pass;
+    } else {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "StateMismatch",
+        key: "retries",
+        expected: expectedRetries,
+        actual: retries
+      });
+    }
+  };
+  let statusToString = s => {
+    if (s === "Pending") {
+      return "#Pending";
+    } else {
+      return "#Completed";
+    }
+  };
+  let thenTodoStatus = async (pending, expectedId, expectedStatus) => {
+    let match = await pending;
+    let id = match.id;
+    let actualStatus;
+    actualStatus = match.result.TAG === "Ok" ? "Completed" : "Pending";
+    if (id === expectedId && actualStatus === expectedStatus) {
+      return Outcome$ReventlessGwt.pass;
+    }
+    let encOne = (rid, rstatus) => {
+      let d = {};
+      d["id"] = rid;
+      d["status"] = statusToString(rstatus);
+      return d;
+    };
+    return Outcome$ReventlessGwt.fail({
+      TAG: "StateMismatch",
+      key: id,
+      expected: encOne(expectedId, expectedStatus),
+      actual: encOne(id, actualStatus)
+    });
+  };
+  return {
+    Spec: Spec,
+    describe: JestBind$ReventlessGwt.describe,
+    test: test,
+    testSync: testSync,
+    givenEvent: givenEvent,
+    whenCollect: whenCollect,
+    thenTodos: thenTodos,
+    givenTodo: givenTodo,
+    whenTranslateMocked: whenTranslateMocked,
+    whenTranslateRetrying: whenTranslateRetrying,
+    thenCommand: thenCommand,
+    thenNoCommand: thenNoCommand,
+    thenRetryRecorded: thenRetryRecorded,
+    thenTodoStatus: thenTodoStatus
+  };
+}
+
+export {
+  Make,
+}
+/* S Not a pure module */

package/src/Outcome.res

@@ -0,0 +1,97 @@
+// The `Outcome` algebra — Stage 2 of the reventless-gwt plan.
+//
+// Every `then*` combinator in every GWT DSL returns `Outcome.outcome`
+// (`result<unit, mismatch>`). The runner, the human formatter, the AI loop,
+// and the IDE all consume the same `Outcome` value, just rendered differently.
+//
+// See `docs/analysis/given-when-then-specifications.md` §3.2 for the canonical
+// shape and §3.3 for the JSON rendering. Stage 7 adds sury-aware rendering and
+// structural `fieldDiff`. Stage 4 added `AppendConditionMismatch`.
+
+type mismatch =
+  | EventsMismatch({expected: array<JSON.t>, actual: array<JSON.t>})
+  | ErrorMismatch({
+      expected: JSON.t,
+      actual: option<JSON.t>,
+      actualEvents: array<JSON.t>,
+    })
+  | StateMismatch({key: string, expected: option<JSON.t>, actual: option<JSON.t>})
+  | NoEventExpected({actual: array<JSON.t>})
+  | TodoMismatch({expected: array<(string, JSON.t)>, actual: array<(string, JSON.t)>})
+  | AppendConditionMismatch({expected: JSON.t, actual: JSON.t})
+  | TranslateError({expected: string, actual: option<string>})
+  | QueryRowsMismatch({expected: array<JSON.t>, actual: array<JSON.t>})
+  // The set of published actions (events/commands) emitted by an ExtensionPoint
+  // mapping or an Extension delegate diverged from the expectation. Supports
+  // one-to-many fan-out (one inbound message → N published actions). Used by
+  // `Delegate_GWT` and the cross-plugin `Flow_GWT` boundary steps.
+  | PublishedActionsMismatch({expected: array<JSON.t>, actual: array<JSON.t>})
+  | Throw({error: string, stack: string})
+
+type outcome = result<unit, mismatch>
+
+let pass: outcome = Ok()
+let fail = (m): outcome => Error(m)
+
+let kindName = (m: mismatch) =>
+  switch m {
+  | EventsMismatch(_) => "EventsMismatch"
+  | ErrorMismatch(_) => "ErrorMismatch"
+  | StateMismatch(_) => "StateMismatch"
+  | NoEventExpected(_) => "NoEventExpected"
+  | TodoMismatch(_) => "TodoMismatch"
+  | AppendConditionMismatch(_) => "AppendConditionMismatch"
+  | TranslateError(_) => "TranslateError"
+  | QueryRowsMismatch(_) => "QueryRowsMismatch"
+  | PublishedActionsMismatch(_) => "PublishedActionsMismatch"
+  | Throw(_) => "Throw"
+  }
+
+let stringifyJson = (j: JSON.t) => JSON.stringify(j, ~space=2)
+let stringifyOptJson = (j: option<JSON.t>) =>
+  switch j {
+  | Some(v) => stringifyJson(v)
+  | None => "(none)"
+  }
+let stringifyJsonArray = (arr: array<JSON.t>) =>
+  "[" ++ arr->Array.map(stringifyJson)->Array.join(", ") ++ "]"
+
+let format = (m: mismatch) =>
+  switch m {
+  | EventsMismatch({expected, actual}) =>
+    `EventsMismatch:\n  expected: ${stringifyJsonArray(expected)}\n  actual:   ${stringifyJsonArray(
+        actual,
+      )}`
+  | ErrorMismatch({expected, actual, actualEvents}) =>
+    `ErrorMismatch:\n  expected error: ${stringifyJson(expected)}\n  actual error:   ${stringifyOptJson(
+        actual,
+      )}\n  actual events:  ${stringifyJsonArray(actualEvents)}`
+  | StateMismatch({key, expected, actual}) =>
+    `StateMismatch (key: ${key}):\n  expected: ${stringifyOptJson(
+        expected,
+      )}\n  actual:   ${stringifyOptJson(actual)}`
+  | NoEventExpected({actual}) =>
+    `NoEventExpected: expected no events, got:\n  ${stringifyJsonArray(actual)}`
+  | TodoMismatch({expected, actual}) => {
+      let fmt = arr =>
+        arr
+        ->Array.map(((id, j)) => `(${id}, ${stringifyJson(j)})`)
+        ->Array.join(", ")
+      `TodoMismatch:\n  expected: [${fmt(expected)}]\n  actual:   [${fmt(actual)}]`
+    }
+  | AppendConditionMismatch({expected, actual}) =>
+    `AppendConditionMismatch:\n  expected: ${stringifyJson(expected)}\n  actual:   ${stringifyJson(
+        actual,
+      )}`
+  | TranslateError({expected, actual}) =>
+    `TranslateError:\n  expected: ${expected}\n  actual:   ${actual->Option.getOr("(none)")}`
+  | QueryRowsMismatch({expected, actual}) =>
+    `QueryRowsMismatch:\n  expected: ${stringifyJsonArray(expected)}\n  actual:   ${stringifyJsonArray(
+        actual,
+      )}`
+  | PublishedActionsMismatch({expected, actual}) =>
+    `PublishedActionsMismatch:\n  expected: ${stringifyJsonArray(expected)}\n  actual:   ${stringifyJsonArray(
+        actual,
+      )}`
+  | Throw({error, stack}) => `Throw: ${error}\n${stack}`
+  }

package/src/Outcome.res.mjs

@@ -0,0 +1,93 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function fail(m) {
+  return {
+    TAG: "Error",
+    _0: m
+  };
+}
+
+function kindName(m) {
+  switch (m.TAG) {
+    case "EventsMismatch" :
+      return "EventsMismatch";
+    case "ErrorMismatch" :
+      return "ErrorMismatch";
+    case "StateMismatch" :
+      return "StateMismatch";
+    case "NoEventExpected" :
+      return "NoEventExpected";
+    case "TodoMismatch" :
+      return "TodoMismatch";
+    case "AppendConditionMismatch" :
+      return "AppendConditionMismatch";
+    case "TranslateError" :
+      return "TranslateError";
+    case "QueryRowsMismatch" :
+      return "QueryRowsMismatch";
+    case "PublishedActionsMismatch" :
+      return "PublishedActionsMismatch";
+    case "Throw" :
+      return "Throw";
+  }
+}
+
+function stringifyJson(j) {
+  return JSON.stringify(j, undefined, 2);
+}
+
+function stringifyOptJson(j) {
+  if (j !== undefined) {
+    return JSON.stringify(j, undefined, 2);
+  } else {
+    return "(none)";
+  }
+}
+
+function stringifyJsonArray(arr) {
+  return "[" + arr.map(stringifyJson).join(", ") + "]";
+}
+
+function format(m) {
+  switch (m.TAG) {
+    case "EventsMismatch" :
+      return `EventsMismatch:\n  expected: ` + stringifyJsonArray(m.expected) + `\n  actual:   ` + stringifyJsonArray(m.actual);
+    case "ErrorMismatch" :
+      return `ErrorMismatch:\n  expected error: ` + JSON.stringify(m.expected, undefined, 2) + `\n  actual error:   ` + stringifyOptJson(m.actual) + `\n  actual events:  ` + stringifyJsonArray(m.actualEvents);
+    case "StateMismatch" :
+      return `StateMismatch (key: ` + m.key + `):\n  expected: ` + stringifyOptJson(m.expected) + `\n  actual:   ` + stringifyOptJson(m.actual);
+    case "NoEventExpected" :
+      return `NoEventExpected: expected no events, got:\n  ` + stringifyJsonArray(m.actual);
+    case "TodoMismatch" :
+      let fmt = arr => arr.map(param => `(` + param[0] + `, ` + JSON.stringify(param[1], undefined, 2) + `)`).join(", ");
+      return `TodoMismatch:\n  expected: [` + fmt(m.expected) + `]\n  actual:   [` + fmt(m.actual) + `]`;
+    case "AppendConditionMismatch" :
+      return `AppendConditionMismatch:\n  expected: ` + JSON.stringify(m.expected, undefined, 2) + `\n  actual:   ` + JSON.stringify(m.actual, undefined, 2);
+    case "TranslateError" :
+      return `TranslateError:\n  expected: ` + m.expected + `\n  actual:   ` + Stdlib_Option.getOr(m.actual, "(none)");
+    case "QueryRowsMismatch" :
+      return `QueryRowsMismatch:\n  expected: ` + stringifyJsonArray(m.expected) + `\n  actual:   ` + stringifyJsonArray(m.actual);
+    case "PublishedActionsMismatch" :
+      return `PublishedActionsMismatch:\n  expected: ` + stringifyJsonArray(m.expected) + `\n  actual:   ` + stringifyJsonArray(m.actual);
+    case "Throw" :
+      return `Throw: ` + m.error + `\n` + m.stack;
+  }
+}
+
+let pass = {
+  TAG: "Ok",
+  _0: undefined
+};
+
+export {
+  pass,
+  fail,
+  kindName,
+  stringifyJson,
+  stringifyOptJson,
+  stringifyJsonArray,
+  format,
+}
+/* No side effect */

package/src/PackageScan.res

@@ -0,0 +1,80 @@
+// Derives the set of workspace packages that own GWT test files, so a watch
+// session knows which packages to keep compiling (`pnpm run start` →
+// `rescript build -w`). Given the absolute test-file paths from `Discovery`,
+// each is mapped to its nearest ancestor `package.json` that declares a
+// `start` script; results are deduplicated by directory.
+//
+// This is the input both the `packages` NDJSON event (FormatterVsCode) and the
+// watch-mode build manager (ProcessManager) consume — computed fresh per run so
+// it never drifts when a plugin is added or removed.
+
+type pkg = {
+  // Package name from package.json (may be "" if absent).
+  name: string,
+  // Absolute directory containing the owning package.json.
+  dir: string,
+  // The `start` script's command (the ReScript watch command), informational.
+  build: string,
+}
+
+@module("node:fs") external _existsSync: string => bool = "existsSync"
+@module("node:fs") external _readFileSync: (string, string) => string = "readFileSync"
+@module("node:path") external dirname: string => string = "dirname"
+@module("node:path") external join: (string, string) => string = "join"
+
+// Reads name + `start` command from a package.json, if it declares one.
+let readPackage = (pkgJsonPath: string): option<(string, string)> =>
+  try {
+    let json = JSON.parseOrThrow(_readFileSync(pkgJsonPath, "utf8"))
+    switch json {
+    | Object(obj) =>
+      let name = switch obj->Dict.get("name") {
+      | Some(String(n)) => n
+      | _ => ""
+      }
+      switch obj->Dict.get("scripts") {
+      | Some(Object(scripts)) =>
+        switch scripts->Dict.get("start") {
+        | Some(String(cmd)) => Some((name, cmd))
+        | _ => None
+        }
+      | _ => None
+      }
+    | _ => None
+    }
+  } catch {
+  | _ => None
+  }
+
+// Walks up from `dir` to the nearest package.json declaring a `start` script.
+let rec findOwning = (dir: string): option<pkg> => {
+  let pkgJson = join(dir, "package.json")
+  let here = _existsSync(pkgJson) ? readPackage(pkgJson) : None
+  switch here {
+  | Some((name, build)) => Some({name, dir, build})
+  | None => {
+      let parent = dirname(dir)
+      parent == dir ? None : findOwning(parent)
+    }
+  }
+}
+
+// Maps test files → deduplicated owning packages (declaration order preserved).
+let scan = (testFiles: array<string>): array<pkg> => {
+  let seen = Dict.make()
+  let out = []
+  testFiles->Array.forEach(file =>
+    switch findOwning(dirname(file)) {
+    | Some(pkg) =>
+      switch seen->Dict.get(pkg.dir) {
+      | Some(_) => ()
+      | None => {
+          seen->Dict.set(pkg.dir, true)
+          out->Array.push(pkg)
+        }
+      }
+    | None => ()
+    }
+  )
+  out
+}