@sun-asterisk/sungen 3.2.18 → 3.2.20

package/dist/orchestrator/templates/specs-mock.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mock = void 0;
+/** Resource types the fail-on-unmocked guard judges; everything else passes through.
+ *  NOTE: page.route() does NOT intercept WebSocket connections (that is
+ *  page.routeWebSocket, a separate API) — the shipped posture is fetch/XHR only. */
+const GUARDED_TYPES = new Set(['fetch', 'xhr']);
+class MockRouter {
+    constructor() {
+        this.state = new WeakMap();
+    }
+    stateFor(page) {
+        let st = this.state.get(page);
+        if (!st) {
+            st = { counts: new Map(), installed: new Set(), routes: [], guardInstalled: false, passthrough: false, violations: [], backgroundRouteCount: -1, backgroundNames: new Set() };
+            this.state.set(page, st);
+        }
+        return st;
+    }
+    /** `@mock:passthrough` — unmatched requests reach the real backend for this page/scenario.
+     *  Also forgives violations already recorded (Background installs + goto run BEFORE the
+     *  scenario body can set this flag — boot-time requests of an opted-out scenario must not
+     *  fail its assertNoUnmocked verdict). The compiler additionally arms the flag inside
+     *  beforeEach via test.info().tags, before the Background installs, so boot requests are
+     *  not even aborted on the default path. */
+    setPassthrough(page) {
+        const st = this.stateFor(page);
+        st.passthrough = true;
+        st.violations.length = 0;
+    }
+    /** Install one catalog entry. The first install also arms the fail-on-unmocked guard. */
+    async install(page, cfg) {
+        const st = this.stateFor(page);
+        if (!st.guardInstalled) {
+            st.guardInstalled = true;
+            const guard = async (route) => {
+                const req = route.request();
+                if (!GUARDED_TYPES.has(req.resourceType()) || st.passthrough)
+                    return route.fallback();
+                // Record + abort — NEVER throw here: a route handler runs outside any test
+                // stack, so a throw surfaces as an unhandled rejection (a hard process crash
+                // outside @playwright/test, flaky attribution inside it). The compiler emits
+                // `await mock.assertNoUnmocked(page)` at the end of every @mock scenario,
+                // which fails the test deterministically with the FULL violation list.
+                st.violations.push(`${req.method()} ${req.url()}`);
+                await route.abort('failed');
+            };
+            await page.route('**/*', guard); // FIRST → matched last → every named mock wins
+            st.routes.push({ pattern: '**/*', handler: guard });
+        }
+        const pattern = cfg.url.startsWith('re:') ? new RegExp(cfg.url.slice(3)) : cfg.url;
+        const handler = async (route) => {
+            if (cfg.method !== '*' && route.request().method() !== cfg.method)
+                return route.fallback();
+            st.counts.set(cfg.name, (st.counts.get(cfg.name) ?? 0) + 1);
+            if (cfg.delay_ms)
+                await new Promise((r) => setTimeout(r, cfg.delay_ms));
+            // A delayed fulfill can race a page close / reset at teardown — that race must
+            // not surface as an unhandled rejection from inside a route handler.
+            try {
+                await route.fulfill({ status: cfg.status, headers: cfg.headers, body: cfg.body });
+            }
+            catch { /* page closing */ }
+        };
+        await page.route(pattern, handler);
+        st.routes.push({ pattern, handler });
+        st.installed.add(cfg.name);
+        if (!st.counts.has(cfg.name))
+            st.counts.set(cfg.name, 0);
+    }
+    /** Handled-request count for a mock installed in THIS scenario — throws for a name
+     *  that was never installed here (an exact 0 on an uninstalled mock must be a loud
+     *  error, not a passing assertion). */
+    callCount(page, name) {
+        const st = this.state.get(page);
+        if (!st || !st.installed.has(name)) {
+            throw new Error(`mock "${name}" was never installed in this scenario — add \`Given [${name}] mock is active\``);
+        }
+        return st.counts.get(name) ?? 0;
+    }
+    /** Fail-on-unmocked verdict — emitted by the compiler as the LAST statement of every
+     *  @mock scenario. Throws with the full list of aborted unmatched requests; a scenario
+     *  whose app swallowed those failed fetches must not stay green for the wrong reason. */
+    async assertNoUnmocked(page) {
+        const st = this.state.get(page);
+        if (!st || st.violations.length === 0)
+            return;
+        const list = st.violations.slice();
+        st.violations.length = 0;
+        throw new Error(`${list.length} unmocked request(s) hit the fail-on-unmocked guard:\n  - ${list.join('\n  - ')}\n` +
+            'Add entries to mock/mocks.yaml, or opt out with @mock:passthrough.');
+    }
+    /** @serial only, emitted by the compiler at the END of the Background block (beforeAll):
+     *  everything installed so far — Background mocks and the guard — persists across the
+     *  feature's scenarios; reset() removes only what each scenario added on top. Without
+     *  this, scenario 1's reset would kill the Background mocks and scenarios 2+ would run
+     *  against the REAL backend with no guard — the silent-green class this driver exists
+     *  to prevent. */
+    snapshotBackground(page) {
+        const st = this.stateFor(page);
+        st.backgroundRouteCount = st.routes.length;
+        st.backgroundNames = new Set(st.installed);
+    }
+    /** Scoped teardown for the @serial shared page: unroute exactly what THIS scenario
+     *  installed (Background routes captured by snapshotBackground persist), zero every
+     *  counter, clear flags/violations. Emitted at the end of each @mock scenario on the
+     *  serial path; the default per-test path never needs it (page dies with the test). */
+    async reset(page) {
+        const st = this.state.get(page);
+        if (!st)
+            return;
+        if (st.backgroundRouteCount < 0) {
+            // No Background snapshot → drop everything (the pre-snapshot / default behavior).
+            for (const r of st.routes) {
+                try {
+                    await page.unroute(r.pattern, r.handler);
+                }
+                catch { /* page may be closing */ }
+            }
+            this.state.delete(page);
+            return;
+        }
+        for (const r of st.routes.slice(st.backgroundRouteCount)) {
+            try {
+                await page.unroute(r.pattern, r.handler);
+            }
+            catch { /* page may be closing */ }
+        }
+        st.routes.length = st.backgroundRouteCount;
+        st.installed = new Set(st.backgroundNames);
+        st.counts = new Map();
+        st.violations.length = 0;
+        st.passthrough = false;
+    }
+}
+exports.mock = new MockRouter();
+//# sourceMappingURL=specs-mock.js.map

package/dist/orchestrator/templates/specs-mock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-mock.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-mock.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/templates/specs-mock.ts

@@ -0,0 +1,179 @@
+/* eslint-disable */
+/**
+ * Sungen Mock Driver — runtime network-mocking helper (auto-generated into specs/mock.ts).
+ *
+ * One module singleton (same import shape as db/api); ALL state lives per-page in a
+ * WeakMap<Page, MockState>, so routes and call counters follow the page's lifetime on
+ * both isolation paths: a fresh page per test destroys them for free, and the @serial
+ * shared page is reset by the compiler-emitted mock.reset(page) at the end of each
+ * @mock scenario (scoped — only routes THIS router installed are unrouted; a blanket
+ * page.unrouteAll() would also kill Background-installed mocks and third-party routes).
+ *
+ * Blocking posture (fail-on-unmocked, the project default): the first install() also
+ * registers a catch-all route. Playwright matches routes last-registered-first, so
+ * registering the catch-all FIRST makes every named mock win over it. The catch-all
+ * only judges fetch/XHR/websocket traffic — documents/scripts/styles/images pass, the
+ * app shell must still load; what is being isolated is API traffic. An unmatched API
+ * request aborts and throws (fails the test) unless the scenario opted out via
+ * @mock:passthrough (compiled to mock.setPassthrough(page)).
+ *
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import type { Page, Route } from '@playwright/test';
+
+export interface MockConfig {
+  name: string;
+  method: string;               // HTTP verb or '*'
+  url: string;                  // page.route glob, or 're:<pattern>' for a regex
+  status: number;
+  headers?: Record<string, string>;
+  body?: string;                // pre-serialized by the compiler (JSON string)
+  delay_ms?: number;
+}
+
+interface InstalledRoute {
+  pattern: string | RegExp;
+  handler: (route: Route) => Promise<void>;
+}
+
+interface MockState {
+  counts: Map<string, number>;      // per-mock handled-request counters
+  installed: Set<string>;           // names installed in this scenario (callCount guard)
+  routes: InstalledRoute[];         // exactly what WE routed (scoped reset)
+  guardInstalled: boolean;
+  passthrough: boolean;
+  violations: string[];             // unmocked requests the guard aborted (fail-on-unmocked)
+  /** @serial only: routes[0..N) / names installed by Background (beforeAll) persist across
+   *  scenarios — reset() removes only what a scenario added on top. -1 = no snapshot
+   *  (the default per-test path), where reset() drops the whole state. */
+  backgroundRouteCount: number;
+  backgroundNames: Set<string>;
+}
+
+/** Resource types the fail-on-unmocked guard judges; everything else passes through.
+ *  NOTE: page.route() does NOT intercept WebSocket connections (that is
+ *  page.routeWebSocket, a separate API) — the shipped posture is fetch/XHR only. */
+const GUARDED_TYPES = new Set(['fetch', 'xhr']);
+
+class MockRouter {
+  private state = new WeakMap<Page, MockState>();
+
+  private stateFor(page: Page): MockState {
+    let st = this.state.get(page);
+    if (!st) {
+      st = { counts: new Map(), installed: new Set(), routes: [], guardInstalled: false, passthrough: false, violations: [], backgroundRouteCount: -1, backgroundNames: new Set() };
+      this.state.set(page, st);
+    }
+    return st;
+  }
+
+  /** `@mock:passthrough` — unmatched requests reach the real backend for this page/scenario.
+   *  Also forgives violations already recorded (Background installs + goto run BEFORE the
+   *  scenario body can set this flag — boot-time requests of an opted-out scenario must not
+   *  fail its assertNoUnmocked verdict). The compiler additionally arms the flag inside
+   *  beforeEach via test.info().tags, before the Background installs, so boot requests are
+   *  not even aborted on the default path. */
+  setPassthrough(page: Page): void {
+    const st = this.stateFor(page);
+    st.passthrough = true;
+    st.violations.length = 0;
+  }
+
+  /** Install one catalog entry. The first install also arms the fail-on-unmocked guard. */
+  async install(page: Page, cfg: MockConfig): Promise<void> {
+    const st = this.stateFor(page);
+    if (!st.guardInstalled) {
+      st.guardInstalled = true;
+      const guard = async (route: Route) => {
+        const req = route.request();
+        if (!GUARDED_TYPES.has(req.resourceType()) || st.passthrough) return route.fallback();
+        // Record + abort — NEVER throw here: a route handler runs outside any test
+        // stack, so a throw surfaces as an unhandled rejection (a hard process crash
+        // outside @playwright/test, flaky attribution inside it). The compiler emits
+        // `await mock.assertNoUnmocked(page)` at the end of every @mock scenario,
+        // which fails the test deterministically with the FULL violation list.
+        st.violations.push(`${req.method()} ${req.url()}`);
+        await route.abort('failed');
+      };
+      await page.route('**/*', guard); // FIRST → matched last → every named mock wins
+      st.routes.push({ pattern: '**/*', handler: guard });
+    }
+
+    const pattern = cfg.url.startsWith('re:') ? new RegExp(cfg.url.slice(3)) : cfg.url;
+    const handler = async (route: Route) => {
+      if (cfg.method !== '*' && route.request().method() !== cfg.method) return route.fallback();
+      st.counts.set(cfg.name, (st.counts.get(cfg.name) ?? 0) + 1);
+      if (cfg.delay_ms) await new Promise((r) => setTimeout(r, cfg.delay_ms));
+      // A delayed fulfill can race a page close / reset at teardown — that race must
+      // not surface as an unhandled rejection from inside a route handler.
+      try { await route.fulfill({ status: cfg.status, headers: cfg.headers, body: cfg.body }); } catch { /* page closing */ }
+    };
+    await page.route(pattern, handler);
+    st.routes.push({ pattern, handler });
+    st.installed.add(cfg.name);
+    if (!st.counts.has(cfg.name)) st.counts.set(cfg.name, 0);
+  }
+
+  /** Handled-request count for a mock installed in THIS scenario — throws for a name
+   *  that was never installed here (an exact 0 on an uninstalled mock must be a loud
+   *  error, not a passing assertion). */
+  callCount(page: Page, name: string): number {
+    const st = this.state.get(page);
+    if (!st || !st.installed.has(name)) {
+      throw new Error(`mock "${name}" was never installed in this scenario — add \`Given [${name}] mock is active\``);
+    }
+    return st.counts.get(name) ?? 0;
+  }
+
+  /** Fail-on-unmocked verdict — emitted by the compiler as the LAST statement of every
+   *  @mock scenario. Throws with the full list of aborted unmatched requests; a scenario
+   *  whose app swallowed those failed fetches must not stay green for the wrong reason. */
+  async assertNoUnmocked(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st || st.violations.length === 0) return;
+    const list = st.violations.slice();
+    st.violations.length = 0;
+    throw new Error(
+      `${list.length} unmocked request(s) hit the fail-on-unmocked guard:\n  - ${list.join('\n  - ')}\n` +
+      'Add entries to mock/mocks.yaml, or opt out with @mock:passthrough.');
+  }
+
+  /** @serial only, emitted by the compiler at the END of the Background block (beforeAll):
+   *  everything installed so far — Background mocks and the guard — persists across the
+   *  feature's scenarios; reset() removes only what each scenario added on top. Without
+   *  this, scenario 1's reset would kill the Background mocks and scenarios 2+ would run
+   *  against the REAL backend with no guard — the silent-green class this driver exists
+   *  to prevent. */
+  snapshotBackground(page: Page): void {
+    const st = this.stateFor(page);
+    st.backgroundRouteCount = st.routes.length;
+    st.backgroundNames = new Set(st.installed);
+  }
+
+  /** Scoped teardown for the @serial shared page: unroute exactly what THIS scenario
+   *  installed (Background routes captured by snapshotBackground persist), zero every
+   *  counter, clear flags/violations. Emitted at the end of each @mock scenario on the
+   *  serial path; the default per-test path never needs it (page dies with the test). */
+  async reset(page: Page): Promise<void> {
+    const st = this.state.get(page);
+    if (!st) return;
+    if (st.backgroundRouteCount < 0) {
+      // No Background snapshot → drop everything (the pre-snapshot / default behavior).
+      for (const r of st.routes) {
+        try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+      }
+      this.state.delete(page);
+      return;
+    }
+    for (const r of st.routes.slice(st.backgroundRouteCount)) {
+      try { await page.unroute(r.pattern, r.handler); } catch { /* page may be closing */ }
+    }
+    st.routes.length = st.backgroundRouteCount;
+    st.installed = new Set(st.backgroundNames);
+    st.counts = new Map();
+    st.violations.length = 0;
+    st.passthrough = false;
+  }
+}
+
+export const mock = new MockRouter();

package/dist/orchestrator/templates/specs-url-assert.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
+ *
+ * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ *
+ * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
+ * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
+ * generated suite in the field: regenerate everything, re-review every newly-red test. Behind a
+ * helper the same correction ships as a runtime patch. The generator's job shrinks to what it
+ * alone knows — the pathname pattern — and the semantics live in one readable place.
+ *
+ * Why a predicate and not two assertions. The shape before this one was
+ *   await expect(page).toHaveURL(/\/vi\/search/);      // unanchored: passes on /vi/search-x
+ *   expect(page.url()).toContain('<query>');           // synchronous, one-shot: never retries
+ * — two half-checks, neither anchored, and nothing ever compared pathname and query together.
+ * `toHaveURL(predicate)` is web-first (it retries like any other assertion), receives a parsed
+ * URL, and needs no regex escaping of runtime values, which is what forced the split.
+ */
+export interface UrlExpectation {
+    /**
+     * Anchored pathname pattern, compiled by the generator from the page selector's `value`
+     * (`:id` segments already wildcarded). Anchored against `u.pathname` ONLY: pathname never
+     * carries the query, so `^…$` is exact there — the same source that was unsafe to anchor
+     * against a full URL.
+     */
+    pathname: RegExp;
+    /**
+     * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
+     * `undefined` means the step declared nothing, which is itself an assertion — see below.
+     */
+    declared?: string;
+    /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
+    dataRef?: string;
+}
+/**
+ * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
+ * (`Given User is on [X] page with {{v}}`).
+ *
+ * Why this is not a plain `base + path + value`. It used to be, and an author writing the value as a
+ * whole relative URL — the habit the assertion side already had to accommodate — navigated to
+ * `/vi/search/vi/search?q=1`: the page's own path, twice. The Then side then asserted the real path
+ * correctly, so the scenario could never go green.
+ *
+ * `base` (the configured baseURL, possibly '') and `path` (the page selector's value) arrive
+ * SEPARATELY so a value that carries its own rooted path replaces the page's path without also
+ * discarding a path prefix baked into the baseURL — a deployment under `https://host/tenant-a`
+ * would otherwise navigate to the wrong tenant, and only when a `with {{v}}` was present, which is
+ * exactly the kind of inconsistency nobody would think to look for.
+ *
+ * What it deliberately does NOT do is sanitize. A test may legitimately drive a MALFORMED query to
+ * prove the app rejects it (issue #464), so anything that is not a duplicated path is appended
+ * verbatim: no encoding, no normalising, no reordering.
+ */
+export declare function joinPath(base: string, path: string, declared?: string | null): string;
+/**
+ * Build the predicate for `expect(page).toHaveURL(...)`.
+ *
+ * Query semantics are deliberately asymmetric:
+ *   no `with {{v}}`  → the URL must carry NO query. A bare page means a bare page, so
+ *                      `/vi/search` does not pass on `/vi/search?x=1`.
+ *   `with {{v}}`     → every declared param must match; extra params are tolerated, so a
+ *                      tracking/UTM param the test never cared about cannot turn it red.
+ *                      A declared fragment is asserted too; a declared value carrying no query
+ *                      at all constrains the path only (the compiler warns: SG-W014).
+ */
+export declare function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean;
+//# sourceMappingURL=specs-url-assert.d.ts.map

package/dist/orchestrator/templates/specs-url-assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-url-assert.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrF;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,cAAc,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAuC/F"}

package/dist/orchestrator/templates/specs-url-assert.js

@@ -0,0 +1,121 @@
+"use strict";
+/* eslint-disable */
+/**
+ * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
+ *
+ * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ *
+ * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
+ * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
+ * generated suite in the field: regenerate everything, re-review every newly-red test. Behind a
+ * helper the same correction ships as a runtime patch. The generator's job shrinks to what it
+ * alone knows — the pathname pattern — and the semantics live in one readable place.
+ *
+ * Why a predicate and not two assertions. The shape before this one was
+ *   await expect(page).toHaveURL(/\/vi\/search/);      // unanchored: passes on /vi/search-x
+ *   expect(page.url()).toContain('<query>');           // synchronous, one-shot: never retries
+ * — two half-checks, neither anchored, and nothing ever compared pathname and query together.
+ * `toHaveURL(predicate)` is web-first (it retries like any other assertion), receives a parsed
+ * URL, and needs no regex escaping of runtime values, which is what forced the split.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinPath = joinPath;
+exports.urlMatches = urlMatches;
+/**
+ * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
+ * (`Given User is on [X] page with {{v}}`).
+ *
+ * Why this is not a plain `base + path + value`. It used to be, and an author writing the value as a
+ * whole relative URL — the habit the assertion side already had to accommodate — navigated to
+ * `/vi/search/vi/search?q=1`: the page's own path, twice. The Then side then asserted the real path
+ * correctly, so the scenario could never go green.
+ *
+ * `base` (the configured baseURL, possibly '') and `path` (the page selector's value) arrive
+ * SEPARATELY so a value that carries its own rooted path replaces the page's path without also
+ * discarding a path prefix baked into the baseURL — a deployment under `https://host/tenant-a`
+ * would otherwise navigate to the wrong tenant, and only when a `with {{v}}` was present, which is
+ * exactly the kind of inconsistency nobody would think to look for.
+ *
+ * What it deliberately does NOT do is sanitize. A test may legitimately drive a MALFORMED query to
+ * prove the app rejects it (issue #464), so anything that is not a duplicated path is appended
+ * verbatim: no encoding, no normalising, no reordering.
+ */
+function joinPath(base, path, declared) {
+    if (declared === undefined || declared === null || declared === '')
+        return base + path;
+    const value = String(declared);
+    // A query/fragment appends — the overwhelmingly common shape, and the only one #464 needs.
+    if (value.startsWith('?') || value.startsWith('#'))
+        return base + path + value;
+    // An absolute URL replaces everything: the author pasted a full address.
+    if (/^[a-z]+:\/\//i.test(value))
+        return value;
+    // A rooted path carries its own path, so it replaces the PAGE's path while everything the
+    // baseURL contributed — scheme, host, and any path prefix — is kept.
+    if (value.startsWith('/'))
+        return base + value;
+    // Anything else is raw input the test wants appended as-is.
+    return base + path + value;
+}
+/**
+ * `u.pathname` is percent-encoded; a regex built from a selector's literal `value` is not, so a
+ * non-ASCII route (`/読取結果一覧`) could never match. Decoding can throw on a lone `%`, in which
+ * case the raw form is all there is.
+ */
+function decodedPath(pathname) {
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return pathname;
+    }
+}
+/**
+ * Build the predicate for `expect(page).toHaveURL(...)`.
+ *
+ * Query semantics are deliberately asymmetric:
+ *   no `with {{v}}`  → the URL must carry NO query. A bare page means a bare page, so
+ *                      `/vi/search` does not pass on `/vi/search?x=1`.
+ *   `with {{v}}`     → every declared param must match; extra params are tolerated, so a
+ *                      tracking/UTM param the test never cared about cannot turn it red.
+ *                      A declared fragment is asserted too; a declared value carrying no query
+ *                      at all constrains the path only (the compiler warns: SG-W014).
+ */
+function urlMatches({ pathname, declared, dataRef }) {
+    return (u) => {
+        if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname)))
+            return false;
+        // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
+        // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
+        // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
+        // bare), the second is broken test-data. Only the generator knows which, and it says so by
+        // emitting `dataRef` exactly when the step carried a `with {{v}}`.
+        if (!dataRef)
+            return u.search === '';
+        // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
+        // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these
+        // throws say "your test-data is wrong, and here is the key". An empty value used to parse to
+        // an empty param list, and `[].every()` is vacuously TRUE — it passed on any query at all.
+        if (declared === undefined || declared === null) {
+            throw new Error(`url assertion: test-data key "${dataRef}" is missing — nothing to assert`);
+        }
+        if (String(declared).trim() === '') {
+            throw new Error(`url assertion: test-data key "${dataRef}" is empty — nothing to assert`);
+        }
+        // Parsing against the live pathname as base lets ONE expression handle every shape an author
+        // writes: '?q=1' (query only), '/vi/search?q=1' (a whole relative URL — its path is ignored,
+        // the page selector already owns the path), and '#tab' (fragment only). The predecessor
+        // regex-stripped the prefix instead, which silently turned a value with NO query
+        // ('/vi/search') into a bogus param NAME — an assertion that could never be satisfied.
+        const d = new URL(String(declared), 'http://sungen.invalid' + u.pathname);
+        // getAll, not get: a multi-select filter (?tag=a&tag=b) is the exact case this assertion is
+        // for, and `get()` returns only the first value — so the correct URL failed. Comparing as a
+        // subset per key keeps this consistent with "extra params are tolerated", and makes param
+        // order meaningless, which is what a URL actually means.
+        const queryOk = [...d.searchParams].every(([k, v]) => u.searchParams.getAll(k).includes(v));
+        // Only assert a fragment the author actually declared.
+        const hashOk = !d.hash || d.hash === u.hash;
+        return queryOk && hashOk;
+    };
+}
+//# sourceMappingURL=specs-url-assert.js.map

package/dist/orchestrator/templates/specs-url-assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-url-assert.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"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"}