@devfellowship/components 3.0.1 → 3.1.0

package/dist/testing.cjs

@@ -0,0 +1,171 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var testing_exports = {};
+__export(testing_exports, {
+  IAM_MEMBER_MIN_LEVEL: () => IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError: () => VacuousVerificationError,
+  assertNotVacuouslyEmpty: () => assertNotVacuouslyEmpty,
+  classifyEmptiness: () => classifyEmptiness,
+  iamMemberProbe: () => iamMemberProbe
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/testing/emptiness.ts
+function classifyEmptiness(input) {
+  const { rowCount, deniedSignalPresent, viewerIsAuthorized } = input;
+  if (rowCount > 0) {
+    return {
+      verdict: "populated",
+      reason: `Surface rendered ${rowCount} row(s); the result is non-empty, so there is no emptiness to disambiguate.`
+    };
+  }
+  if (deniedSignalPresent) {
+    return {
+      verdict: "denied",
+      reason: "Surface rendered 0 rows AND an explicit permission-denied signal. The app failed loud, so the emptiness is attributable to a stated authorization failure rather than to a silent RLS filter \u2014 an assertion on this state is meaningful."
+    };
+  }
+  if (viewerIsAuthorized === true) {
+    return {
+      verdict: "genuinely-empty",
+      reason: "Surface rendered 0 rows with no permission-denied signal, and an independent authorization probe confirmed the viewer COULD have seen rows. The emptiness therefore reflects the data, not the viewer's access."
+    };
+  }
+  const authClause = viewerIsAuthorized === false ? "an independent probe reported the viewer is NOT authorized" : "the viewer's authorization could not be confirmed (unknown)";
+  return {
+    verdict: "vacuous",
+    reason: `Surface rendered 0 rows, the page rendered NO permission-denied signal, and ${authClause}. Supabase RLS hides unauthorized rows as HTTP 200 with an empty body, which is byte-identical to a genuinely empty result \u2014 so this emptiness is indistinguishable from lack of access and the check proves nothing. Fix by supplying an independent authorization signal (e.g. \`iamMemberProbe\`), by using an identity that can see rows, or by making the surface render an explicit permission-denied state.`
+  };
+}
+
+// src/testing/assert-not-vacuously-empty.ts
+var VacuousVerificationError = class extends Error {
+  constructor(details) {
+    super(
+      [
+        `Vacuous verification on "${details.surface}": this check proves nothing.`,
+        "",
+        `  \u2022 the surface returned ${details.rowCount} rows (nothing to assert against)`,
+        "  \u2022 the page rendered NO permission-denied signal, so the app did not fail loud",
+        details.viewerIsAuthorized === false ? "  \u2022 the viewer is known NOT to be authorized" : "  \u2022 the viewer's authorization could NOT be confirmed",
+        "",
+        details.reason
+      ].join("\n")
+    );
+    this.verdict = "vacuous";
+    this.name = "VacuousVerificationError";
+    this.surface = details.surface;
+    this.rowCount = details.rowCount;
+    this.deniedSignalPresent = details.deniedSignalPresent;
+    this.viewerIsAuthorized = details.viewerIsAuthorized;
+    this.reason = details.reason;
+  }
+};
+async function resolveAuthorization(input) {
+  if (input === void 0) return "unknown";
+  if (typeof input !== "function") return input;
+  try {
+    const result = await input();
+    return result === true || result === false ? result : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function resolveRowCount(page, opts) {
+  if (opts.countText) {
+    const text = await page.locator(opts.countTextSelector ?? "body").innerText();
+    for (const rawLine of text.split("\n")) {
+      const match = opts.countText.exec(rawLine.trim());
+      if (match) {
+        const parsed = Number(match[1]);
+        if (Number.isFinite(parsed)) return parsed;
+      }
+    }
+    if (!opts.rowSelector) {
+      throw new Error(
+        `assertNotVacuouslyEmpty: countText ${String(opts.countText)} matched no line of "${opts.countTextSelector ?? "body"}". The row count is unreadable, so no verdict is possible \u2014 fix the pattern or pass rowSelector.`
+      );
+    }
+  }
+  if (opts.rowSelector) return page.locator(opts.rowSelector).count();
+  throw new Error(
+    "assertNotVacuouslyEmpty: pass countText and/or rowSelector \u2014 without one there is no row count to classify."
+  );
+}
+async function assertNotVacuouslyEmpty(page, opts = {}) {
+  const surface = opts.surface ?? "unnamed surface";
+  const rowCount = await resolveRowCount(page, opts);
+  const deniedSignalPresent = opts.deniedSelector ? await page.locator(opts.deniedSelector).count() > 0 : false;
+  const viewerIsAuthorized = await resolveAuthorization(opts.viewerIsAuthorized);
+  const { verdict, reason } = classifyEmptiness({
+    rowCount,
+    deniedSignalPresent,
+    viewerIsAuthorized
+  });
+  if (verdict === "vacuous") {
+    throw new VacuousVerificationError({
+      surface,
+      rowCount,
+      deniedSignalPresent,
+      viewerIsAuthorized,
+      reason
+    });
+  }
+  return verdict;
+}
+
+// src/testing/iam-member-probe.ts
+var IAM_MEMBER_MIN_LEVEL = 50;
+function readLevel(row) {
+  if (typeof row !== "object" || row === null) return null;
+  const level = row.level;
+  if (typeof level === "number" && Number.isFinite(level)) return level;
+  if (typeof level === "string" && level.trim() !== "") {
+    const parsed = Number(level);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+async function iamMemberProbe(supabaseClient, opts = {}) {
+  const minLevel = opts.minLevel ?? IAM_MEMBER_MIN_LEVEL;
+  const rpcName = opts.rpcName ?? "get_my_iam_role";
+  let data;
+  let error;
+  try {
+    ({ data, error } = await supabaseClient.rpc(rpcName));
+  } catch {
+    return "unknown";
+  }
+  if (error) return "unknown";
+  const rows = Array.isArray(data) ? data : data == null ? [] : [data];
+  if (rows.length === 0) return "unknown";
+  const levels = rows.map(readLevel).filter((l) => l !== null);
+  if (levels.length === 0) return "unknown";
+  return levels.some((level) => level >= minLevel);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError,
+  assertNotVacuouslyEmpty,
+  classifyEmptiness,
+  iamMemberProbe
+});

package/dist/testing.d.cts

@@ -0,0 +1,210 @@
+/**
+ * Layer 1 — the pure decision. No I/O, no Playwright, no Supabase.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Agents verify UI through Playwright using a shared smoke identity that has
+ * IAM global level 0. Supabase RLS on `iam.is_member()`-gated tables returns
+ * ZERO ROWS WITH HTTP 200 — not 403. So the page renders "no results" and an
+ * assertion like `expect(rows).toHaveCount(0)` or "the page loaded without an
+ * error" passes VACUOUSLY: satisfied by absence of permission rather than by
+ * the state under test.
+ *
+ * Measured 2026-08-07: spec-builder `/history` showed "0 registros" to the
+ * smoke account while `work.ai_spec_inputs` held 17 rows. Every assertion on
+ * that page was green.
+ *
+ * THE HONEST PART
+ * ---------------
+ * PostgREST cannot tell "RLS hid it" from "genuinely empty" — both are
+ * `200 []`. There is no detector that can recover the difference from the
+ * response alone, and this module does not pretend otherwise. What it does
+ * instead is NAME the ambiguity and refuse to let a test claim a green it did
+ * not earn: an empty surface only proves something when we have an
+ * INDEPENDENT signal that the viewer was authorized to see rows (or that the
+ * app told us, loudly, that it was not).
+ */
+/**
+ * The four states an empty-looking surface can actually be in.
+ *
+ * - `populated`       — rows are present. Nothing ambiguous.
+ * - `denied`          — empty, and the app rendered a permission-denied
+ *                       signal. The app failed LOUD; that is correct
+ *                       behaviour, and asserting emptiness here is meaningful.
+ * - `genuinely-empty` — empty, no denied signal, and we independently know the
+ *                       viewer WAS authorized. Safe: the emptiness is real.
+ * - `vacuous`         — empty, no denied signal, and the viewer's
+ *                       authorization is `false` or could not be confirmed.
+ *                       The check proves nothing. This is the failure.
+ */
+type EmptinessVerdict = "populated" | "denied" | "genuinely-empty" | "vacuous";
+interface ClassifyEmptinessInput {
+    /** How many rows/items the surface actually rendered. */
+    rowCount: number;
+    /**
+     * Did the page render an explicit permission-denied affordance (banner,
+     * `data-testid="access-denied"`, 403 state)? An app that fails loud is
+     * verifiable; an app that renders a silent empty list is not.
+     */
+    deniedSignalPresent: boolean;
+    /**
+     * INDEPENDENT authorization signal — must NOT be derived from the same
+     * response whose emptiness is in question, or the reasoning is circular.
+     * `'unknown'` is the correct value when no independent probe ran; it is
+     * deliberately treated exactly as harshly as `false`.
+     */
+    viewerIsAuthorized: boolean | "unknown";
+}
+interface EmptinessClassification {
+    verdict: EmptinessVerdict;
+    /** Human-readable justification, safe to embed in a failure message. */
+    reason: string;
+}
+/**
+ * Classify what an (apparently) empty surface actually proves.
+ *
+ * Pure function: same input, same verdict, no clock, no network. Every I/O
+ * concern lives in Layer 2 (`assertNotVacuouslyEmpty`).
+ */
+declare function classifyEmptiness(input: ClassifyEmptinessInput): EmptinessClassification;
+
+/**
+ * Structural (duck-typed) subset of the Playwright surface this entry needs.
+ *
+ * WHY NOT `import type { Page } from "@playwright/test"`
+ * -----------------------------------------------------
+ * `@devfellowship/components` is a runtime dependency of every DFL app.
+ * Adding Playwright — even as a type-only import — would put a ~100MB test
+ * runner into the dependency graph of production bundles and would make this
+ * entry impossible to unit-test without a browser. So we declare the three
+ * methods we actually call and nothing else.
+ *
+ * A real Playwright `Page` / `Locator` satisfies these interfaces
+ * structurally: no adapter, no cast, no `@playwright/test` in package.json.
+ * A plain object literal satisfies them too, which is how the tests work.
+ */
+/** The slice of a Playwright `Locator` used here. */
+interface LocatorLike {
+    /** Number of DOM elements the selector currently resolves to. */
+    count(): Promise<number>;
+    /** Rendered (visible) text of the resolved element. */
+    innerText(): Promise<string>;
+}
+/** The slice of a Playwright `Page` used here. */
+interface PageLike {
+    locator(selector: string): LocatorLike;
+}
+/**
+ * Minimal shape of a `supabase-js` client — only `.rpc()`, only the fields
+ * `iamMemberProbe` reads. Keeps `@supabase/supabase-js` out of this entry's
+ * imports entirely (it is an OPTIONAL peer dependency of the package).
+ */
+interface SupabaseRpcClientLike {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+
+/**
+ * Thrown when a surface's emptiness is indistinguishable from lack of access.
+ *
+ * This is NOT "the page is broken" — it is "this check cannot tell you whether
+ * the page is broken", which is the more dangerous state, because the default
+ * assertion would have passed.
+ */
+declare class VacuousVerificationError extends Error {
+    readonly verdict: EmptinessVerdict;
+    readonly surface: string;
+    readonly rowCount: number;
+    readonly deniedSignalPresent: boolean;
+    readonly viewerIsAuthorized: boolean | "unknown";
+    readonly reason: string;
+    constructor(details: {
+        surface: string;
+        rowCount: number;
+        deniedSignalPresent: boolean;
+        viewerIsAuthorized: boolean | "unknown";
+        reason: string;
+    });
+}
+interface AssertNotVacuouslyEmptyOptions {
+    /**
+     * Regex matched against the surface's rendered text, LINE BY LINE (each line
+     * trimmed), so anchored patterns work — e.g. `/^(\d+) registros?$/`.
+     * Capture group 1 must be the count.
+     */
+    countText?: RegExp;
+    /** CSS/testid selector whose element holds the count text. Default `body`. */
+    countTextSelector?: string;
+    /** Alternative to `countText`: count the elements matching this selector. */
+    rowSelector?: string;
+    /**
+     * Selector for the element/testid the app renders on permission denial.
+     * If the app has no such affordance, omit it — but then a denied surface is
+     * unverifiable by construction, which is exactly what `vacuous` reports.
+     */
+    deniedSelector?: string;
+    /**
+     * INDEPENDENT authorization signal. A thunk (e.g. `() => iamMemberProbe(sb)`)
+     * is awaited; if it throws, the result is `'unknown'`.
+     * Omitted defaults to `'unknown'` — treated as harshly as `false`.
+     */
+    viewerIsAuthorized?: boolean | "unknown" | (() => Promise<boolean | "unknown">);
+    /** Label used in the failure message. Default `unnamed surface`. */
+    surface?: string;
+}
+/**
+ * Layer 2 — the e2e adapter. Reads the three facts off a Playwright-ish page,
+ * hands them to the pure {@link classifyEmptiness}, and refuses to return a
+ * green it cannot justify.
+ *
+ * Returns the {@link EmptinessVerdict} for `populated`, `denied` and
+ * `genuinely-empty`. Throws {@link VacuousVerificationError} for `vacuous`.
+ *
+ * @example
+ * // Fails today against the level-0 smoke identity — by design.
+ * await assertNotVacuouslyEmpty(page, {
+ *   surface: "spec-builder /history",
+ *   countText: /^(\d+) registros?$/,
+ *   deniedSelector: '[data-testid="access-denied"]',
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function assertNotVacuouslyEmpty(page: PageLike, opts?: AssertNotVacuouslyEmptyOptions): Promise<EmptinessVerdict>;
+
+/**
+ * Default IAM level that counts as "member enough to see gated rows".
+ * Mirrors the threshold `iam.is_member()` enforces server-side.
+ */
+declare const IAM_MEMBER_MIN_LEVEL = 50;
+/**
+ * Independent authorization probe: ask the database who the caller is,
+ * instead of inferring it from the very response whose emptiness is in doubt.
+ *
+ * Calls the existing `get_my_iam_role()` RPC (already granted to
+ * `authenticated`; returns rows of `{ role_id, level }`) and resolves whether
+ * any granted role clears `minLevel` (default {@link IAM_MEMBER_MIN_LEVEL}).
+ *
+ * FAILS TO `'unknown'`, NEVER TO `true`. An RPC error, a null payload, a
+ * non-array payload, or rows carrying no readable `level` all mean "we did not
+ * learn anything" — and `'unknown'` is treated by `classifyEmptiness` exactly
+ * as harshly as `false`. A probe that guessed optimistically would reintroduce
+ * the very false-green this module exists to prevent.
+ *
+ * Note that an empty row set is `'unknown'` rather than `false`: a level-0
+ * identity may legitimately produce zero rows, but so does a broken grant, and
+ * the two are not distinguishable from here. Both block a green.
+ *
+ * @example
+ * await assertNotVacuouslyEmpty(page, {
+ *   countText: /^(\d+) registros?$/,
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function iamMemberProbe(supabaseClient: SupabaseRpcClientLike, opts?: {
+    minLevel?: number;
+    rpcName?: string;
+}): Promise<boolean | "unknown">;
+
+export { type AssertNotVacuouslyEmptyOptions, type ClassifyEmptinessInput, type EmptinessClassification, type EmptinessVerdict, IAM_MEMBER_MIN_LEVEL, type LocatorLike, type PageLike, type SupabaseRpcClientLike, VacuousVerificationError, assertNotVacuouslyEmpty, classifyEmptiness, iamMemberProbe };

package/dist/testing.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Layer 1 — the pure decision. No I/O, no Playwright, no Supabase.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Agents verify UI through Playwright using a shared smoke identity that has
+ * IAM global level 0. Supabase RLS on `iam.is_member()`-gated tables returns
+ * ZERO ROWS WITH HTTP 200 — not 403. So the page renders "no results" and an
+ * assertion like `expect(rows).toHaveCount(0)` or "the page loaded without an
+ * error" passes VACUOUSLY: satisfied by absence of permission rather than by
+ * the state under test.
+ *
+ * Measured 2026-08-07: spec-builder `/history` showed "0 registros" to the
+ * smoke account while `work.ai_spec_inputs` held 17 rows. Every assertion on
+ * that page was green.
+ *
+ * THE HONEST PART
+ * ---------------
+ * PostgREST cannot tell "RLS hid it" from "genuinely empty" — both are
+ * `200 []`. There is no detector that can recover the difference from the
+ * response alone, and this module does not pretend otherwise. What it does
+ * instead is NAME the ambiguity and refuse to let a test claim a green it did
+ * not earn: an empty surface only proves something when we have an
+ * INDEPENDENT signal that the viewer was authorized to see rows (or that the
+ * app told us, loudly, that it was not).
+ */
+/**
+ * The four states an empty-looking surface can actually be in.
+ *
+ * - `populated`       — rows are present. Nothing ambiguous.
+ * - `denied`          — empty, and the app rendered a permission-denied
+ *                       signal. The app failed LOUD; that is correct
+ *                       behaviour, and asserting emptiness here is meaningful.
+ * - `genuinely-empty` — empty, no denied signal, and we independently know the
+ *                       viewer WAS authorized. Safe: the emptiness is real.
+ * - `vacuous`         — empty, no denied signal, and the viewer's
+ *                       authorization is `false` or could not be confirmed.
+ *                       The check proves nothing. This is the failure.
+ */
+type EmptinessVerdict = "populated" | "denied" | "genuinely-empty" | "vacuous";
+interface ClassifyEmptinessInput {
+    /** How many rows/items the surface actually rendered. */
+    rowCount: number;
+    /**
+     * Did the page render an explicit permission-denied affordance (banner,
+     * `data-testid="access-denied"`, 403 state)? An app that fails loud is
+     * verifiable; an app that renders a silent empty list is not.
+     */
+    deniedSignalPresent: boolean;
+    /**
+     * INDEPENDENT authorization signal — must NOT be derived from the same
+     * response whose emptiness is in question, or the reasoning is circular.
+     * `'unknown'` is the correct value when no independent probe ran; it is
+     * deliberately treated exactly as harshly as `false`.
+     */
+    viewerIsAuthorized: boolean | "unknown";
+}
+interface EmptinessClassification {
+    verdict: EmptinessVerdict;
+    /** Human-readable justification, safe to embed in a failure message. */
+    reason: string;
+}
+/**
+ * Classify what an (apparently) empty surface actually proves.
+ *
+ * Pure function: same input, same verdict, no clock, no network. Every I/O
+ * concern lives in Layer 2 (`assertNotVacuouslyEmpty`).
+ */
+declare function classifyEmptiness(input: ClassifyEmptinessInput): EmptinessClassification;
+
+/**
+ * Structural (duck-typed) subset of the Playwright surface this entry needs.
+ *
+ * WHY NOT `import type { Page } from "@playwright/test"`
+ * -----------------------------------------------------
+ * `@devfellowship/components` is a runtime dependency of every DFL app.
+ * Adding Playwright — even as a type-only import — would put a ~100MB test
+ * runner into the dependency graph of production bundles and would make this
+ * entry impossible to unit-test without a browser. So we declare the three
+ * methods we actually call and nothing else.
+ *
+ * A real Playwright `Page` / `Locator` satisfies these interfaces
+ * structurally: no adapter, no cast, no `@playwright/test` in package.json.
+ * A plain object literal satisfies them too, which is how the tests work.
+ */
+/** The slice of a Playwright `Locator` used here. */
+interface LocatorLike {
+    /** Number of DOM elements the selector currently resolves to. */
+    count(): Promise<number>;
+    /** Rendered (visible) text of the resolved element. */
+    innerText(): Promise<string>;
+}
+/** The slice of a Playwright `Page` used here. */
+interface PageLike {
+    locator(selector: string): LocatorLike;
+}
+/**
+ * Minimal shape of a `supabase-js` client — only `.rpc()`, only the fields
+ * `iamMemberProbe` reads. Keeps `@supabase/supabase-js` out of this entry's
+ * imports entirely (it is an OPTIONAL peer dependency of the package).
+ */
+interface SupabaseRpcClientLike {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+
+/**
+ * Thrown when a surface's emptiness is indistinguishable from lack of access.
+ *
+ * This is NOT "the page is broken" — it is "this check cannot tell you whether
+ * the page is broken", which is the more dangerous state, because the default
+ * assertion would have passed.
+ */
+declare class VacuousVerificationError extends Error {
+    readonly verdict: EmptinessVerdict;
+    readonly surface: string;
+    readonly rowCount: number;
+    readonly deniedSignalPresent: boolean;
+    readonly viewerIsAuthorized: boolean | "unknown";
+    readonly reason: string;
+    constructor(details: {
+        surface: string;
+        rowCount: number;
+        deniedSignalPresent: boolean;
+        viewerIsAuthorized: boolean | "unknown";
+        reason: string;
+    });
+}
+interface AssertNotVacuouslyEmptyOptions {
+    /**
+     * Regex matched against the surface's rendered text, LINE BY LINE (each line
+     * trimmed), so anchored patterns work — e.g. `/^(\d+) registros?$/`.
+     * Capture group 1 must be the count.
+     */
+    countText?: RegExp;
+    /** CSS/testid selector whose element holds the count text. Default `body`. */
+    countTextSelector?: string;
+    /** Alternative to `countText`: count the elements matching this selector. */
+    rowSelector?: string;
+    /**
+     * Selector for the element/testid the app renders on permission denial.
+     * If the app has no such affordance, omit it — but then a denied surface is
+     * unverifiable by construction, which is exactly what `vacuous` reports.
+     */
+    deniedSelector?: string;
+    /**
+     * INDEPENDENT authorization signal. A thunk (e.g. `() => iamMemberProbe(sb)`)
+     * is awaited; if it throws, the result is `'unknown'`.
+     * Omitted defaults to `'unknown'` — treated as harshly as `false`.
+     */
+    viewerIsAuthorized?: boolean | "unknown" | (() => Promise<boolean | "unknown">);
+    /** Label used in the failure message. Default `unnamed surface`. */
+    surface?: string;
+}
+/**
+ * Layer 2 — the e2e adapter. Reads the three facts off a Playwright-ish page,
+ * hands them to the pure {@link classifyEmptiness}, and refuses to return a
+ * green it cannot justify.
+ *
+ * Returns the {@link EmptinessVerdict} for `populated`, `denied` and
+ * `genuinely-empty`. Throws {@link VacuousVerificationError} for `vacuous`.
+ *
+ * @example
+ * // Fails today against the level-0 smoke identity — by design.
+ * await assertNotVacuouslyEmpty(page, {
+ *   surface: "spec-builder /history",
+ *   countText: /^(\d+) registros?$/,
+ *   deniedSelector: '[data-testid="access-denied"]',
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function assertNotVacuouslyEmpty(page: PageLike, opts?: AssertNotVacuouslyEmptyOptions): Promise<EmptinessVerdict>;
+
+/**
+ * Default IAM level that counts as "member enough to see gated rows".
+ * Mirrors the threshold `iam.is_member()` enforces server-side.
+ */
+declare const IAM_MEMBER_MIN_LEVEL = 50;
+/**
+ * Independent authorization probe: ask the database who the caller is,
+ * instead of inferring it from the very response whose emptiness is in doubt.
+ *
+ * Calls the existing `get_my_iam_role()` RPC (already granted to
+ * `authenticated`; returns rows of `{ role_id, level }`) and resolves whether
+ * any granted role clears `minLevel` (default {@link IAM_MEMBER_MIN_LEVEL}).
+ *
+ * FAILS TO `'unknown'`, NEVER TO `true`. An RPC error, a null payload, a
+ * non-array payload, or rows carrying no readable `level` all mean "we did not
+ * learn anything" — and `'unknown'` is treated by `classifyEmptiness` exactly
+ * as harshly as `false`. A probe that guessed optimistically would reintroduce
+ * the very false-green this module exists to prevent.
+ *
+ * Note that an empty row set is `'unknown'` rather than `false`: a level-0
+ * identity may legitimately produce zero rows, but so does a broken grant, and
+ * the two are not distinguishable from here. Both block a green.
+ *
+ * @example
+ * await assertNotVacuouslyEmpty(page, {
+ *   countText: /^(\d+) registros?$/,
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function iamMemberProbe(supabaseClient: SupabaseRpcClientLike, opts?: {
+    minLevel?: number;
+    rpcName?: string;
+}): Promise<boolean | "unknown">;
+
+export { type AssertNotVacuouslyEmptyOptions, type ClassifyEmptinessInput, type EmptinessClassification, type EmptinessVerdict, IAM_MEMBER_MIN_LEVEL, type LocatorLike, type PageLike, type SupabaseRpcClientLike, VacuousVerificationError, assertNotVacuouslyEmpty, classifyEmptiness, iamMemberProbe };

package/dist/testing.js

@@ -0,0 +1,140 @@
+// src/testing/emptiness.ts
+function classifyEmptiness(input) {
+  const { rowCount, deniedSignalPresent, viewerIsAuthorized } = input;
+  if (rowCount > 0) {
+    return {
+      verdict: "populated",
+      reason: `Surface rendered ${rowCount} row(s); the result is non-empty, so there is no emptiness to disambiguate.`
+    };
+  }
+  if (deniedSignalPresent) {
+    return {
+      verdict: "denied",
+      reason: "Surface rendered 0 rows AND an explicit permission-denied signal. The app failed loud, so the emptiness is attributable to a stated authorization failure rather than to a silent RLS filter \u2014 an assertion on this state is meaningful."
+    };
+  }
+  if (viewerIsAuthorized === true) {
+    return {
+      verdict: "genuinely-empty",
+      reason: "Surface rendered 0 rows with no permission-denied signal, and an independent authorization probe confirmed the viewer COULD have seen rows. The emptiness therefore reflects the data, not the viewer's access."
+    };
+  }
+  const authClause = viewerIsAuthorized === false ? "an independent probe reported the viewer is NOT authorized" : "the viewer's authorization could not be confirmed (unknown)";
+  return {
+    verdict: "vacuous",
+    reason: `Surface rendered 0 rows, the page rendered NO permission-denied signal, and ${authClause}. Supabase RLS hides unauthorized rows as HTTP 200 with an empty body, which is byte-identical to a genuinely empty result \u2014 so this emptiness is indistinguishable from lack of access and the check proves nothing. Fix by supplying an independent authorization signal (e.g. \`iamMemberProbe\`), by using an identity that can see rows, or by making the surface render an explicit permission-denied state.`
+  };
+}
+
+// src/testing/assert-not-vacuously-empty.ts
+var VacuousVerificationError = class extends Error {
+  constructor(details) {
+    super(
+      [
+        `Vacuous verification on "${details.surface}": this check proves nothing.`,
+        "",
+        `  \u2022 the surface returned ${details.rowCount} rows (nothing to assert against)`,
+        "  \u2022 the page rendered NO permission-denied signal, so the app did not fail loud",
+        details.viewerIsAuthorized === false ? "  \u2022 the viewer is known NOT to be authorized" : "  \u2022 the viewer's authorization could NOT be confirmed",
+        "",
+        details.reason
+      ].join("\n")
+    );
+    this.verdict = "vacuous";
+    this.name = "VacuousVerificationError";
+    this.surface = details.surface;
+    this.rowCount = details.rowCount;
+    this.deniedSignalPresent = details.deniedSignalPresent;
+    this.viewerIsAuthorized = details.viewerIsAuthorized;
+    this.reason = details.reason;
+  }
+};
+async function resolveAuthorization(input) {
+  if (input === void 0) return "unknown";
+  if (typeof input !== "function") return input;
+  try {
+    const result = await input();
+    return result === true || result === false ? result : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function resolveRowCount(page, opts) {
+  if (opts.countText) {
+    const text = await page.locator(opts.countTextSelector ?? "body").innerText();
+    for (const rawLine of text.split("\n")) {
+      const match = opts.countText.exec(rawLine.trim());
+      if (match) {
+        const parsed = Number(match[1]);
+        if (Number.isFinite(parsed)) return parsed;
+      }
+    }
+    if (!opts.rowSelector) {
+      throw new Error(
+        `assertNotVacuouslyEmpty: countText ${String(opts.countText)} matched no line of "${opts.countTextSelector ?? "body"}". The row count is unreadable, so no verdict is possible \u2014 fix the pattern or pass rowSelector.`
+      );
+    }
+  }
+  if (opts.rowSelector) return page.locator(opts.rowSelector).count();
+  throw new Error(
+    "assertNotVacuouslyEmpty: pass countText and/or rowSelector \u2014 without one there is no row count to classify."
+  );
+}
+async function assertNotVacuouslyEmpty(page, opts = {}) {
+  const surface = opts.surface ?? "unnamed surface";
+  const rowCount = await resolveRowCount(page, opts);
+  const deniedSignalPresent = opts.deniedSelector ? await page.locator(opts.deniedSelector).count() > 0 : false;
+  const viewerIsAuthorized = await resolveAuthorization(opts.viewerIsAuthorized);
+  const { verdict, reason } = classifyEmptiness({
+    rowCount,
+    deniedSignalPresent,
+    viewerIsAuthorized
+  });
+  if (verdict === "vacuous") {
+    throw new VacuousVerificationError({
+      surface,
+      rowCount,
+      deniedSignalPresent,
+      viewerIsAuthorized,
+      reason
+    });
+  }
+  return verdict;
+}
+
+// src/testing/iam-member-probe.ts
+var IAM_MEMBER_MIN_LEVEL = 50;
+function readLevel(row) {
+  if (typeof row !== "object" || row === null) return null;
+  const level = row.level;
+  if (typeof level === "number" && Number.isFinite(level)) return level;
+  if (typeof level === "string" && level.trim() !== "") {
+    const parsed = Number(level);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+async function iamMemberProbe(supabaseClient, opts = {}) {
+  const minLevel = opts.minLevel ?? IAM_MEMBER_MIN_LEVEL;
+  const rpcName = opts.rpcName ?? "get_my_iam_role";
+  let data;
+  let error;
+  try {
+    ({ data, error } = await supabaseClient.rpc(rpcName));
+  } catch {
+    return "unknown";
+  }
+  if (error) return "unknown";
+  const rows = Array.isArray(data) ? data : data == null ? [] : [data];
+  if (rows.length === 0) return "unknown";
+  const levels = rows.map(readLevel).filter((l) => l !== null);
+  if (levels.length === 0) return "unknown";
+  return levels.some((level) => level >= minLevel);
+}
+export {
+  IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError,
+  assertNotVacuouslyEmpty,
+  classifyEmptiness,
+  iamMemberProbe
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [
@@ -27,6 +27,11 @@
       "import": "./dist/providers.js",
       "require": "./dist/providers.cjs"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
     "./styles": "./dist/styles/theme.css",
     "./shadcn": "./dist/styles/shadcn.css",
     "./tokens": "./dist/styles/tokens.css",
@@ -52,7 +57,8 @@
     "prepublishOnly": "npm run build",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "lint:no-docs": "node scripts/check-no-storybook-docs.mjs"
+    "lint:no-docs": "node scripts/check-no-storybook-docs.mjs",
+    "check:cli-offline": "node scripts/check-cli-bundle-offline.mjs"
   },
   "peerDependencies": {
     "@supabase/supabase-js": ">=2.0.0",