@specific.dev/spectest 0.60.2 → 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);

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/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.2",
+  "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[] {

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/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 {