@specific.dev/spectest 0.60.1 → 0.61.0

package/dist/daemon.js

@@ -114,7 +114,7 @@ let loaded = null;
 /** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
  *  keep the call sites reading off the suite. */
 function casesMetadata(suite) {
-    return catalogueCases(suite?.tests);
+    return catalogueCases(suite?.tests, APP_DIR);
 }
 function groupsMetadata(suite) {
     return catalogueGroups(suite?.tests);
@@ -3115,6 +3115,26 @@ async function runCoverageAdapters(svc) {
         clearTimeout(timer);
     }
 }
+/** Container name → its working directory, read once per container
+ *  (`docker inspect`); forks with the env like the rest of module memory.
+ *  Empty when the image sets none (paths are then reported from `/`). */
+const COVERAGE_ROOTS = new Map();
+async function coverageRoot(service) {
+    const cached = COVERAGE_ROOTS.get(service);
+    if (cached !== undefined)
+        return cached;
+    let root = "";
+    try {
+        const r = await docker(["inspect", "-f", "{{.Config.WorkingDir}}", service], 10_000);
+        if (r.code === 0)
+            root = r.stdout.trim();
+    }
+    catch {
+        // Best-effort: the tree then falls back to a common-prefix guess.
+    }
+    COVERAGE_ROOTS.set(service, root);
+    return root;
+}
 async function captureServiceCoverage() {
     const l = loaded;
     if (!l)
@@ -3130,6 +3150,9 @@ async function captureServiceCoverage() {
         if (error)
             return { service: svc.name, reports: [], error };
         const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        const root = await coverageRoot(svc.name);
+        if (root)
+            read.root = root;
         // What ships is what ran during this capture, whatever the tool
         // counts: cumulative lcov is subtracted against the previous
         // capture (module memory, forks with the env); a delta adapter's

package/dist/harness/catalogue.d.ts

@@ -21,6 +21,8 @@ export interface CatalogueCase {
             id: string;
         };
     };
+    /** Absolute path of the file that registered the test, if known. */
+    file?: string;
 }
 export interface CaseMeta {
     id: string;
@@ -30,6 +32,9 @@ export interface CaseMeta {
     /** The group this case is shown in, if any. Display only — a group never
      *  changes the DAG, which `dependsOn` still describes in full. */
     groupId?: string;
+    /** Project-relative path (`spectest/tests/…`) of the file that defines
+     *  the test, when the SDK recorded one and it lies under `appDir`. */
+    file?: string;
 }
 /** A display-only test group (`env.group(...)`), for the CLI tree and the
  *  dashboard. `dependsOn` is the group's own level: every member of the
@@ -39,7 +44,12 @@ export interface GroupMeta {
     name: string;
     dependsOn?: string;
 }
-export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[];
+export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined, appDir?: string): CaseMeta[];
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export declare function relativeTestFile(file: string | undefined, appDir: string | undefined): string | undefined;
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

package/dist/harness/catalogue.js

@@ -5,7 +5,7 @@
  * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
  * `cases`) return this, so the mapping lives in one place.
  */
-export function casesMetadata(cases) {
+export function casesMetadata(cases, appDir) {
     if (!cases)
         return [];
     return cases.map((t) => ({
@@ -14,8 +14,21 @@ export function casesMetadata(cases) {
         dependsOn: t.dependsOn?.id,
         timeoutMs: t.timeoutMs,
         groupId: t.group?.id,
+        file: relativeTestFile(t.file, appDir),
     }));
 }
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export function relativeTestFile(file, appDir) {
+    if (!file || !appDir)
+        return undefined;
+    const root = appDir.endsWith("/") ? appDir : appDir + "/";
+    if (!file.startsWith(root))
+        return undefined;
+    return file.slice(root.length);
+}
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

package/dist/harness/coverage.d.ts

@@ -17,6 +17,12 @@ export interface CoverageReport {
 export interface ServiceCoverageCapture {
     service: string;
     reports: CoverageReport[];
+    /** The container's working directory (`docker inspect`), the root
+     *  the reported container paths are relative to for a `COPY . <dir>`
+     *  image. The server strips it to draw a project-relative tree; it
+     *  never has to fetch code to do so. Absent for a container it could
+     *  not be read from. */
+    root?: string;
     /** Set when the capture failed: the command failed, the directory was
      *  empty, no file held an `SF:` record, or the reports were too large.
      *  A case with an error here fails — a hole in the coverage data must

package/dist/index.d.ts

@@ -903,6 +903,11 @@ export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F ex
     readonly group?: TestGroup<unknown, S, F>;
     /** Override the default per-test timeout (default 60s). */
     readonly timeoutMs?: number;
+    /** @internal — absolute path of the file that called `env.test(...)`,
+     *  read off the call stack at registration. The catalogue reports it
+     *  project-relative so a change to a test file can select exactly the
+     *  cases it defines (subset runs). Absent when the stack gave none. */
+    readonly file?: string;
     /** @internal — the body that the in-sandbox daemon invokes. */
     readonly run: TestFn<T, unknown, S, F>;
 }

package/dist/index.js

@@ -470,9 +470,36 @@ maybeFn) {
         dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
         group: opts.group,
         timeoutMs: opts.timeoutMs,
+        file: callerFile(),
         run: fn,
     };
 }
+/**
+ * The file of the nearest stack frame outside this module — the test file
+ * that called `env.test(...)`. Frames look like `at fn (/abs/path.ts:1:2)`
+ * or `at /abs/path.ts:1:2`; the first one whose path is not this module's
+ * is the caller. `undefined` when the stack is unavailable.
+ */
+function callerFile() {
+    const stack = new Error().stack;
+    if (!stack)
+        return undefined;
+    let self;
+    for (const line of stack.split("\n")) {
+        const m = /\(?((?:\/|[A-Za-z]:\\)[^\s()]+?):\d+:\d+\)?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const file = m[1];
+        // The first path on the stack is this module (callerFile itself).
+        if (self === undefined) {
+            self = file;
+            continue;
+        }
+        if (file !== self)
+            return file;
+    }
+    return undefined;
+}
 function validateSuite(suite) {
     const seenIds = new Map();
     for (const t of suite.tests) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.60.1",
+  "version": "0.61.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -286,7 +286,7 @@ let loaded: Loaded | null = null;
 /** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
  *  keep the call sites reading off the suite. */
 function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
-  return catalogueCases(suite?.tests);
+  return catalogueCases(suite?.tests, APP_DIR);
 }
 
 function groupsMetadata(suite: TestSuite | undefined): GroupMeta[] {
@@ -3759,6 +3759,25 @@ async function runCoverageAdapters(
   }
 }
 
+/** Container name → its working directory, read once per container
+ *  (`docker inspect`); forks with the env like the rest of module memory.
+ *  Empty when the image sets none (paths are then reported from `/`). */
+const COVERAGE_ROOTS = new Map<string, string>();
+
+async function coverageRoot(service: string): Promise<string> {
+  const cached = COVERAGE_ROOTS.get(service);
+  if (cached !== undefined) return cached;
+  let root = "";
+  try {
+    const r = await docker(["inspect", "-f", "{{.Config.WorkingDir}}", service], 10_000);
+    if (r.code === 0) root = r.stdout.trim();
+  } catch {
+    // Best-effort: the tree then falls back to a common-prefix guess.
+  }
+  COVERAGE_ROOTS.set(service, root);
+  return root;
+}
+
 async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
@@ -3771,6 +3790,8 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
       const { error, deltaReports } = await runCoverageAdapters(svc);
       if (error) return { service: svc.name, reports: [], error };
       const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+      const root = await coverageRoot(svc.name);
+      if (root) read.root = root;
       // What ships is what ran during this capture, whatever the tool
       // counts: cumulative lcov is subtracted against the previous
       // capture (module memory, forks with the env); a delta adapter's

package/src/harness/catalogue.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { casesMetadata, groupsMetadata, type CatalogueCase } from "./catalogue";
+import { casesMetadata, groupsMetadata, relativeTestFile, type CatalogueCase } from "./catalogue";
 
 const billing = { id: "billing", name: "Billing" };
 const errors = {
@@ -59,3 +59,11 @@ describe("groupsMetadata", () => {
     expect(groupsMetadata(undefined)).toEqual([]);
   });
 });
+
+test("relativeTestFile reports a test file relative to the app dir, or nothing", () => {
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", "/opt/spectest/app")).toBe("spectest/tests/a.ts");
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", "/opt/spectest/app/")).toBe("spectest/tests/a.ts");
+  expect(relativeTestFile("/elsewhere/a.ts", "/opt/spectest/app")).toBeUndefined();
+  expect(relativeTestFile(undefined, "/opt/spectest/app")).toBeUndefined();
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", undefined)).toBeUndefined();
+});

package/src/harness/catalogue.ts

@@ -14,6 +14,8 @@ export interface CatalogueCase {
   dependsOn?: { id: string };
   timeoutMs?: number;
   group?: { id: string; name: string; dependsOn?: { id: string } };
+  /** Absolute path of the file that registered the test, if known. */
+  file?: string;
 }
 
 export interface CaseMeta {
@@ -24,6 +26,9 @@ export interface CaseMeta {
   /** The group this case is shown in, if any. Display only — a group never
    *  changes the DAG, which `dependsOn` still describes in full. */
   groupId?: string;
+  /** Project-relative path (`spectest/tests/…`) of the file that defines
+   *  the test, when the SDK recorded one and it lies under `appDir`. */
+  file?: string;
 }
 
 /** A display-only test group (`env.group(...)`), for the CLI tree and the
@@ -35,7 +40,10 @@ export interface GroupMeta {
   dependsOn?: string;
 }
 
-export function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[] {
+export function casesMetadata(
+  cases: readonly CatalogueCase[] | undefined,
+  appDir?: string,
+): CaseMeta[] {
   if (!cases) return [];
   return cases.map((t) => ({
     id: t.id,
@@ -43,9 +51,21 @@ export function casesMetadata(cases: readonly CatalogueCase[] | undefined): Case
     dependsOn: t.dependsOn?.id,
     timeoutMs: t.timeoutMs,
     groupId: t.group?.id,
+    file: relativeTestFile(t.file, appDir),
   }));
 }
 
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export function relativeTestFile(file: string | undefined, appDir: string | undefined): string | undefined {
+  if (!file || !appDir) return undefined;
+  const root = appDir.endsWith("/") ? appDir : appDir + "/";
+  if (!file.startsWith(root)) return undefined;
+  return file.slice(root.length);
+}
+
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

package/src/harness/coverage.ts

@@ -57,6 +57,12 @@ export interface CoverageReport {
 export interface ServiceCoverageCapture {
   service: string;
   reports: CoverageReport[];
+  /** The container's working directory (`docker inspect`), the root
+   *  the reported container paths are relative to for a `COPY . <dir>`
+   *  image. The server strips it to draw a project-relative tree; it
+   *  never has to fetch code to do so. Absent for a container it could
+   *  not be read from. */
+  root?: string;
   /** Set when the capture failed: the command failed, the directory was
    *  empty, no file held an `SF:` record, or the reports were too large.
    *  A case with an error here fails — a hole in the coverage data must

package/src/index.ts

@@ -1407,6 +1407,11 @@ export interface TestCase<
   readonly group?: TestGroup<unknown, S, F>;
   /** Override the default per-test timeout (default 60s). */
   readonly timeoutMs?: number;
+  /** @internal — absolute path of the file that called `env.test(...)`,
+   *  read off the call stack at registration. The catalogue reports it
+   *  project-relative so a change to a test file can select exactly the
+   *  cases it defines (subset runs). Absent when the stack gave none. */
+  readonly file?: string;
   /** @internal — the body that the in-sandbox daemon invokes. */
   readonly run: TestFn<T, unknown, S, F>;
 }
@@ -2375,10 +2380,35 @@ function buildTestCase(
     dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
     group: opts.group,
     timeoutMs: opts.timeoutMs,
+    file: callerFile(),
     run: fn,
   };
 }
 
+/**
+ * The file of the nearest stack frame outside this module — the test file
+ * that called `env.test(...)`. Frames look like `at fn (/abs/path.ts:1:2)`
+ * or `at /abs/path.ts:1:2`; the first one whose path is not this module's
+ * is the caller. `undefined` when the stack is unavailable.
+ */
+function callerFile(): string | undefined {
+  const stack = new Error().stack;
+  if (!stack) return undefined;
+  let self: string | undefined;
+  for (const line of stack.split("\n")) {
+    const m = /\(?((?:\/|[A-Za-z]:\\)[^\s()]+?):\d+:\d+\)?\s*$/.exec(line);
+    if (!m) continue;
+    const file = m[1]!;
+    // The first path on the stack is this module (callerFile itself).
+    if (self === undefined) {
+      self = file;
+      continue;
+    }
+    if (file !== self) return file;
+  }
+  return undefined;
+}
+
 /** The two option shapes as one, for the untyped runtime implementation.
  *  The public overloads keep them apart — see {@link TestOpts}. */
 interface AnyTestOpts {