@am_shork/attest 0.6.0 → 0.7.1

package/dist/runtime.d.ts

@@ -1,12 +1,32 @@
 /**
  * Group scenarios that verify one requirement. The describe block is named
  * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ *
+ * The body is handed to `describe` untouched. It used to be wrapped in a
+ * set-and-restore of a module-level `currentReqId` that `scenario()` read; that
+ * variable is deleted rather than repaired — see `scenario`.
  */
 export declare function requirement(id: string, body: () => void): void;
 /**
  * Declare a single verifiable scenario. Must be nested inside requirement().
  * The assertion itself is delegated to Vitest `it` (design §3).
  *
+ * **The nesting check happens when the scenario runs, not when it is
+ * collected**, and that is what makes grouping work. Vitest defers a nested
+ * `describe`'s callback until after the parent's has returned — measured: at
+ * the end of the outer callback the inner one has not run — so a module-level
+ * `currentReqId` set and restored around `body()` was already back to `null` by
+ * the time a grouped `scenario()` ran. It threw, and a throw during collection
+ * is a *file* error: nothing in that file was collected, so every scenario in
+ * it came back `declared-not-run` — including correct ungrouped ones under
+ * other requirements — each blamed on "skipped, or excluded by an .only?".
+ * Meanwhile `check` and `cover` read the same file statically and reported full
+ * coverage, so the static half called a file green that could not execute at
+ * all.
+ *
+ * Checking here costs nothing and fails better: a scenario genuinely outside
+ * any `requirement()` now fails as one test instead of taking its file down.
+ *
  * `timeoutMs` is passed straight through to `it`. It exists because `verify`
  * runs the suite **isolated** (§5.4) — no `vitest.config.ts` unless
  * `--vitest-config` names one — so Vitest's 5-second default is what every

package/dist/runtime.js

@@ -2,27 +2,53 @@
 // Pure delegation to Vitest; no in-process coverage singleton — coverage is
 // reconstructed from the Vitest task tree instead (design §5.4).
 import { describe, it } from 'vitest';
-let currentReqId = null;
+import { requirementIdOf, requirementSuiteName } from './core/req-suite.js';
 /**
  * Group scenarios that verify one requirement. The describe block is named
  * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ *
+ * The body is handed to `describe` untouched. It used to be wrapped in a
+ * set-and-restore of a module-level `currentReqId` that `scenario()` read; that
+ * variable is deleted rather than repaired — see `scenario`.
  */
 export function requirement(id, body) {
-    describe(`[${id}]`, () => {
-        const prev = currentReqId;
-        currentReqId = id;
-        try {
-            body();
-        }
-        finally {
-            currentReqId = prev;
-        }
-    });
+    describe(requirementSuiteName(id), body);
+}
+/**
+ * The requirement a scenario actually ended up inside, read from the task tree.
+ *
+ * The same source `runner.ts` attributes coverage from, which is the point: a
+ * module-level "current requirement" was a *second* answer to a question the
+ * suite name already answers, and the two disagreed exactly where it mattered.
+ */
+function owningRequirement(task) {
+    for (let s = task?.suite; s; s = s.suite) {
+        const id = requirementIdOf(s.name ?? '');
+        if (id !== undefined)
+            return id;
+    }
+    return undefined;
 }
 /**
  * Declare a single verifiable scenario. Must be nested inside requirement().
  * The assertion itself is delegated to Vitest `it` (design §3).
  *
+ * **The nesting check happens when the scenario runs, not when it is
+ * collected**, and that is what makes grouping work. Vitest defers a nested
+ * `describe`'s callback until after the parent's has returned — measured: at
+ * the end of the outer callback the inner one has not run — so a module-level
+ * `currentReqId` set and restored around `body()` was already back to `null` by
+ * the time a grouped `scenario()` ran. It threw, and a throw during collection
+ * is a *file* error: nothing in that file was collected, so every scenario in
+ * it came back `declared-not-run` — including correct ungrouped ones under
+ * other requirements — each blamed on "skipped, or excluded by an .only?".
+ * Meanwhile `check` and `cover` read the same file statically and reported full
+ * coverage, so the static half called a file green that could not execute at
+ * all.
+ *
+ * Checking here costs nothing and fails better: a scenario genuinely outside
+ * any `requirement()` now fails as one test instead of taking its file down.
+ *
  * `timeoutMs` is passed straight through to `it`. It exists because `verify`
  * runs the suite **isolated** (§5.4) — no `vitest.config.ts` unless
  * `--vitest-config` names one — so Vitest's 5-second default is what every
@@ -32,9 +58,11 @@ export function requirement(id, body) {
  * for the whole suite, sets one number for what is a property of one scenario.
  */
 export function scenario(name, fn, timeoutMs) {
-    if (!currentReqId) {
-        throw new Error(`scenario("${name}") must be nested inside requirement(...)`);
-    }
-    it(name, fn, timeoutMs);
+    it(name, async (ctx) => {
+        if (owningRequirement(ctx.task) === undefined) {
+            throw new Error(`scenario("${name}") must be nested inside requirement(...)`);
+        }
+        return fn();
+    }, timeoutMs);
 }
 //# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {