@codeyam-editor/codeyam-editor 0.1.7 → 0.1.9

package/npm/scenario-issues.js

@@ -7,6 +7,19 @@ function createIssue(kind, message, extra = {}) {
   };
   if (extra.matchedPattern != null) issue.matchedPattern = extra.matchedPattern;
   if (extra.contextSnippet != null) issue.contextSnippet = extra.contextSnippet;
+  // The hydration gate's cross-origin ATTRIBUTION, carried as data rather than
+  // only as prose. A consumer that must act on the verdict — escalating the
+  // preview off the subpath when the counterpart origin hydrates — would
+  // otherwise have to regex the English message, which breaks the moment the
+  // wording is improved. Same conditional shape as the two fields above so an
+  // issue that carries no attribution serializes exactly as it did before.
+  if (extra.crossOrigin != null) issue.crossOrigin = extra.crossOrigin;
+  if (extra.counterpartUrl != null) issue.counterpartUrl = extra.counterpartUrl;
+  // The dev-server-down verdict, carried as data for the same reason as the
+  // attribution fields above: a consumer that must distinguish "the app served
+  // an error" from "the app was not serving at all" should branch on a field,
+  // not on the prose of the message.
+  if (extra.devServerDown != null) issue.devServerDown = extra.devServerDown;
   return issue;
 }
 
@@ -17,6 +30,42 @@ function pushIssue(issues, issue) {
   }
 }
 
+// Derive which origin a capture actually loaded from, and whether that differs
+// from the origin the VIEWER's browser is served.
+//
+// The two can legitimately differ: the capture browser runs where the app is,
+// the viewer may not, and aiming them independently is what makes a capture
+// work on a cloud VM at all. A capture that renders perfectly from the app's
+// own origin while the user's pane sits on `/__codeyam_preview` is a USEFUL
+// result — but only if the difference travels with it instead of having to be
+// inferred from a URL the reader must parse themselves.
+//
+// Both unknowns resolve toward "no split", never toward a guess. A caller that
+// supplies no `viewerOrigin` (every pre-existing call site) and a `url` with no
+// parseable origin both yield `false`, so no existing consumer sees a changed
+// verdict and an unclassifiable capture is never reported as diverging.
+//
+// Deliberately not reusing `isCrossOriginRequest` from scenario-check.js: that
+// module imports THIS one, so depending on it would invert the dependency, and
+// its fail-safe answers a different question (never strip markers) than this
+// one does (never claim a split).
+function deriveOriginSplit(url, viewerOrigin) {
+  let captureOrigin = null;
+  try {
+    captureOrigin = new URL(url).origin;
+  } catch (_) {
+    /* a malformed or relative capture URL has no origin to report */
+  }
+  return {
+    captureOrigin,
+    viewerOrigin: viewerOrigin ?? null,
+    captureOriginDiffersFromViewer:
+      captureOrigin != null &&
+      viewerOrigin != null &&
+      captureOrigin !== viewerOrigin,
+  };
+}
+
 function buildResult({
   loaded,
   hasContent,
@@ -24,7 +73,15 @@ function buildResult({
   outputPath,
   url,
   unmockedRoutes = [],
+  mockUsage = { used: [], unused: [] },
+  externalRequests = [],
+  viewerOrigin = null,
 }) {
+  const { captureOrigin, captureOriginDiffersFromViewer } = deriveOriginSplit(
+    url,
+    viewerOrigin,
+  );
+
   return {
     ok: loaded && hasContent && issues.length === 0,
     loaded,
@@ -37,6 +94,20 @@ function buildResult({
     // the actionable route list the failure message and `stub-unmocked-routes`
     // consume. Defaults to `[]` so callers that omit it are unchanged.
     unmockedRoutes,
+    // Diagnostic-only, and deliberately NOT part of `ok`: an unused mock is not
+    // automatically an error (a scenario may legitimately declare a mock for a
+    // request the page makes only on interaction). Reporting it turns a silent
+    // inertness into a visible fact; failing on it would break working scenarios
+    // for a heuristic.
+    mockUsage,
+    // Requests grouped by origin, split mocked/unmocked and same/cross-origin.
+    // The line that ends a "why is this page blank" misdiagnosis.
+    externalRequests,
+    // The two hops, named. See `deriveOriginSplit` for why they can differ and
+    // why reporting the difference is not optional.
+    captureOrigin,
+    viewerOrigin,
+    captureOriginDiffersFromViewer,
   };
 }
 
@@ -44,4 +115,5 @@ module.exports = {
   createIssue,
   pushIssue,
   buildResult,
+  deriveOriginSplit,
 };

package/npm/scenario-mocks.js

@@ -1,22 +1,46 @@
-// Route matcher shared, semantically, with the injected live-preview shim
-// (crates/proxy-http/src/fetch_patch.js::matchUrl / matchPath / matchQuerySpec).
-// This is a VERBATIM port of that shim's matcher — the two interception paths
-// MUST agree on which requests a mock route covers. When they drifted (the
-// shim gained `:param` + query-spec parity but this capture-harness matcher was
-// left doing exact string matching), a parameterized or query-spec'd mock
-// rendered in the Live Preview but escaped Playwright's `page.route` during
-// capture and rendered an empty list. `scenario-mocks.test.js` pins the two to
-// identical verdicts on a shared fixture table so a future divergence is a
-// test failure, not another lost build session.
+// Route matcher for the capture harness — one of THREE implementations of a
+// single semantic. The authority is the Rust engine
+// (crates/mock-engine/src/route_parser.rs), where the contract is written down;
+// this file and the injected live-preview shim
+// (crates/proxy-http/src/fetch_patch.js) are ports of it.
 //
-// `:param` path segments match any single non-empty segment; a `?k=v` / `?k=*`
-// query-spec suffix constrains the query as a subset match (`k=*` matches any
-// value; an empty spec matches any query). Full-URL patterns (`http://…`) match
-// by prefix on the raw URL. Mirrors crates/mock-engine's server matcher.
+// This is NOT a verbatim copy of the shim, and describing it as one is what let
+// the drift hide: the two JS matchers agreed with EACH OTHER while both
+// disagreed with the server (they prefix-matched full-URL patterns and returned
+// before applying any query spec, where the server anchored). All three are now
+// pinned against one shared fixture table,
+// crates/mock-engine/fixtures/route-match-fixtures.json, asserted with its
+// expected verdicts by both `scenario-mocks.test.js` and the Rust tests — so a
+// change to one implementation the others do not follow is a test failure, and
+// two matchers agreeing on a wrong answer no longer passes.
+//
+// The semantic, in short (see route_parser.rs for the full contract): `:name`
+// and `*` each match one non-empty path segment; a TRAILING `**` matches the
+// remaining path including `/` and including an empty remainder; a `?k=v` /
+// `?k=*` suffix constrains the query as a subset match. A full-URL pattern
+// (`http://…`) with no wildcard matches by PREFIX — the compatibility rule
+// every shipped external mock relies on — while a wildcarded one matches by the
+// wildcard rules.
 function matchUrl(pattern, url) {
-  // Full-URL patterns (external APIs) match by prefix on the raw URL.
-  if (pattern.startsWith("http://") || pattern.startsWith("https://")) {
-    return url.indexOf(pattern) === 0;
+  // Split the query spec off FIRST — for full-URL and path-only patterns
+  // alike. Returning early for full URLs (as this did) meant a spec like
+  // `?k=*` on an external mock was silently ignored.
+  const pqi = pattern.indexOf("?");
+  const patPath = pqi >= 0 ? pattern.slice(0, pqi) : pattern;
+  const patSpec = pqi >= 0 ? pattern.slice(pqi + 1) : "";
+
+  // Full-URL patterns (external APIs) match against the whole URL, with its
+  // own query stripped before the compare.
+  if (patPath.startsWith("http://") || patPath.startsWith("https://")) {
+    const [rawPath, rawQuery] = splitUrlQuery(url);
+    // Compatibility rule: a wildcard-free full-URL pattern prefix-matches,
+    // which is what every external mock relies on today. A wildcarded one
+    // matches by the wildcard rules, with no prefix fallback.
+    const urlMatched = hasWildcard(patPath)
+      ? matchPath(patPath, rawPath)
+      : rawPath.indexOf(patPath) === 0;
+    if (!urlMatched) return false;
+    return matchQuerySpec(patSpec, rawQuery);
   }
 
   let reqPath = url;
@@ -26,35 +50,71 @@ function matchUrl(pattern, url) {
     reqPath = u.pathname;
     reqQuery = u.search.replace(/^\?/, "");
   } catch {
-    const qi = url.indexOf("?");
-    if (qi >= 0) {
-      reqPath = url.slice(0, qi);
-      reqQuery = url.slice(qi + 1);
-    }
+    [reqPath, reqQuery] = splitUrlQuery(url);
   }
 
-  const patParts = pattern.split("?");
-  if (!matchPath(patParts[0], reqPath)) return false;
-  return matchQuerySpec(patParts.length > 1 ? patParts[1] : "", reqQuery);
+  if (!matchPath(patPath, reqPath)) return false;
+  return matchQuerySpec(patSpec, reqQuery);
+}
+
+// Split a raw URL into [everything-before-the-query, query]. The `#fragment`
+// is dropped from both halves, mirroring the server's strip_url_query.
+function splitUrlQuery(url) {
+  const qi = url.indexOf("?");
+  const hi = url.indexOf("#");
+  const cut = qi < 0 ? hi : hi < 0 ? qi : Math.min(qi, hi);
+  const head = cut < 0 ? url : url.slice(0, cut);
+  if (qi < 0) return [head, ""];
+  const query = url.slice(qi + 1);
+  const fi = query.indexOf("#");
+  return [head, fi >= 0 ? query.slice(0, fi) : query];
+}
+
+// True when a segment is a valid `:name` param. A `:`-prefixed segment with
+// an empty or punctuated name is matched literally, same as the server.
+function isParamSegment(seg) {
+  return /^:[\p{L}\p{N}_]+$/u.test(seg);
 }
 
-// Segment-wise path match with `:param` wildcards. A `:name` segment matches
-// any single non-empty segment; every other segment must be equal, and the
-// segment counts must match — no implicit prefix match, same as the server.
+// True when a segment is any wildcard: `:name`, `*`, or `**`.
+function isWildcardSegment(seg) {
+  return seg === "*" || seg === "**" || isParamSegment(seg);
+}
+
+// True when the pattern contains any wildcard segment.
+function hasWildcard(pattern) {
+  return pattern.split("/").some(isWildcardSegment);
+}
+
+// Segment-wise path match. `:name` and `*` each match any single non-empty
+// segment; a TRAILING `**` matches the remaining path including `/` and
+// including an empty remainder (`/api/**` covers `/api`); every other segment
+// must be equal. No implicit prefix match, same as the server.
 function matchPath(pattern, path) {
   const pp = pattern.split("/");
   const rp = path.split("/");
+  if (pp[pp.length - 1] === "**") {
+    const head = pp.length - 1;
+    if (rp.length < head) return false;
+    for (let i = 0; i < head; i++) {
+      if (!matchSegment(pp[i], rp[i])) return false;
+    }
+    return true;
+  }
   if (pp.length !== rp.length) return false;
   for (let i = 0; i < pp.length; i++) {
-    if (pp[i].charAt(0) === ":") {
-      if (rp[i] === "") return false;
-      continue;
-    }
-    if (pp[i] !== rp[i]) return false;
+    if (!matchSegment(pp[i], rp[i])) return false;
   }
   return true;
 }
 
+// One segment. `:name`, `*`, and a non-final `**` each match any single
+// non-empty segment; anything else must be equal.
+function matchSegment(pat, seg) {
+  if (isWildcardSegment(pat)) return seg !== "";
+  return pat === seg;
+}
+
 // Query-spec match. An empty spec matches any query (a path-only route still
 // matches a request that carries query params). Otherwise every `k=v` pair in
 // the spec must be present in the request query; `k=*` matches any value.
@@ -82,7 +142,11 @@ function splitMockKey(key) {
   return { method: key.slice(0, spaceIdx), route: key.slice(spaceIdx + 1) };
 }
 
-function findHttpMock(httpMocks, request) {
+// The matching mock together with the KEY that declared it, or null. The key is
+// what the usage tally counts — reporting "which declared mock fired" needs the
+// declaration's identity, not just its body, since two keys can carry
+// structurally identical mocks.
+function findHttpMockEntry(httpMocks, request) {
   const method = request.method().toUpperCase();
   const url = request.url();
   for (const [key, mock] of Object.entries(httpMocks)) {
@@ -90,11 +154,16 @@ function findHttpMock(httpMocks, request) {
     if (!parsed) continue;
     // Method stays an exact check; only the route is matched by pattern.
     if (parsed.method.toUpperCase() !== method) continue;
-    if (matchUrl(parsed.route, url)) return mock;
+    if (matchUrl(parsed.route, url)) return { key, mock };
   }
   return null;
 }
 
+function findHttpMock(httpMocks, request) {
+  const entry = findHttpMockEntry(httpMocks, request);
+  return entry ? entry.mock : null;
+}
+
 // The set of path/URL route patterns declared by the mock keys. A key is
 // `"<METHOD> <route>"` (e.g. `"GET /api/plans"`); we strip the method so the
 // route matcher can decide whether a request *could* match any mock without
@@ -121,8 +190,134 @@ function requestTargetsMock(targets, url) {
   return false;
 }
 
-async function attachHttpMocks(page, httpMocks) {
-  if (!httpMocks || Object.keys(httpMocks).length === 0) return;
+// The origin half of a URL, or the raw string when it will not parse. Grouping
+// by origin is what turns twenty tile URLs into one readable line.
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
+// Which declared mock keys actually served a response.
+//
+// This exists because a declared mock whose key never matches any request is
+// silently inert: the capture still reports success, and the frame that lands
+// is the healthy state under a name promising a degraded one. The declared keys
+// were always known; nothing ever compared them against what fired.
+function createMockUsageTally(httpMocks) {
+  const declared = Object.keys(httpMocks || {});
+  const usedKeys = new Set();
+  return {
+    recordFulfilled(key) {
+      usedKeys.add(key);
+    },
+    // Declared order is preserved in both lists so the reported set reads the
+    // same way the scenario's mock block does.
+    get used() {
+      return declared.filter((key) => usedKeys.has(key));
+    },
+    get unused() {
+      return declared.filter((key) => !usedKeys.has(key));
+    },
+  };
+}
+
+// Every request the page made, collapsed to one row per `(origin, mocked)` pair.
+// A full URL list is noise (twenty tile URLs); origin + count + a representative
+// URL is the line that ends a "why is this page blank" misdiagnosis.
+function createRequestInventory(appOrigin) {
+  // Keyed by `origin|mocked` rather than origin alone: an origin serving both a
+  // mocked API call and unmocked sub-resources would otherwise collapse into one
+  // row whose `mocked` flag is a coin toss.
+  const groups = new Map();
+
+  function groupFor(url, mocked) {
+    const origin = originOf(url);
+    const groupKey = `${origin}|${mocked ? "mocked" : "unmocked"}`;
+    let row = groups.get(groupKey);
+    if (!row) {
+      row = {
+        origin,
+        count: 0,
+        sampleUrl: url,
+        mocked: !!mocked,
+        failed: false,
+        // `false` when the capture URL did not parse — the caller then has no
+        // origin to compare against, and treating everything as cross-origin
+        // over-reports rather than hiding a request.
+        sameOrigin: !!appOrigin && origin === appOrigin,
+      };
+      groups.set(groupKey, row);
+    }
+    return row;
+  }
+
+  return {
+    recordRequest(url, mocked) {
+      groupFor(url, mocked).count += 1;
+    },
+    recordFailure(url, mocked) {
+      groupFor(url, mocked).failed = true;
+    },
+    // Busiest origin first — the one worth explaining leads the report.
+    get groups() {
+      return [...groups.values()].sort(
+        (a, b) => b.count - a.count || a.origin.localeCompare(b.origin),
+      );
+    },
+  };
+}
+
+// Composes the two independent halves above into the single handle the capture
+// harness threads through.
+//
+// Purely observational. Nothing here changes which requests are intercepted:
+// `attachHttpMocks` scopes `page.route` to declared targets so unmocked requests
+// load natively, and that scoping is load-bearing (a blanket catch-all route
+// predicate breaks Vite ESM module loading and blanks the SPA).
+function createMockObserver(httpMocks, appOrigin) {
+  const usage = createMockUsageTally(httpMocks);
+  const inventory = createRequestInventory(appOrigin);
+  return {
+    recordFulfilled: (key) => usage.recordFulfilled(key),
+    recordRequest: (url, mocked) => inventory.recordRequest(url, mocked),
+    recordFailure: (url, mocked) => inventory.recordFailure(url, mocked),
+    get used() {
+      return usage.used;
+    },
+    get unused() {
+      return usage.unused;
+    },
+    get externalRequests() {
+      return inventory.groups;
+    },
+  };
+}
+
+// Passive request inventory. `page.on` observes; it never routes, so attaching
+// this cannot change what the page loads.
+function attachRequestInventory(page, observer, httpMocks) {
+  const targets = mockedTargets(httpMocks || {});
+  page.on("request", (request) => {
+    const url = request.url();
+    observer.recordRequest(url, requestTargetsMock(targets, url));
+  });
+  page.on("requestfailed", (request) => {
+    const url = request.url();
+    observer.recordFailure(url, requestTargetsMock(targets, url));
+  });
+}
+
+// Returns the capture's mock observer (see `createMockObserver`). Always returns
+// one, including for a scenario that declares no mocks at all — that is exactly
+// the case where an unexplained third-party fetch is hardest to account for.
+async function attachHttpMocks(page, httpMocks, options = {}) {
+  const observer = createMockObserver(httpMocks, options.appOrigin);
+  attachRequestInventory(page, observer, httpMocks);
+
+  if (!httpMocks || Object.keys(httpMocks).length === 0) return observer;
 
   // Intercept ONLY requests whose path matches a declared mock — not every
   // request. A blanket `page.route("**/*")` intercepts the dev server's ESM
@@ -134,11 +329,15 @@ async function attachHttpMocks(page, httpMocks) {
   await page.route(
     (url) => requestTargetsMock(targets, url),
     async (route) => {
-      const mock = findHttpMock(httpMocks, route.request());
-      if (!mock) {
+      const entry = findHttpMockEntry(httpMocks, route.request());
+      if (!entry) {
         await route.continue();
         return;
       }
+      const { key, mock } = entry;
+      // Counted at the fulfil branch, not at match time: a key is "used" only
+      // when it actually served a response.
+      observer.recordFulfilled(key);
 
       const headers = { ...(mock.headers || {}) };
       let body;
@@ -175,6 +374,8 @@ async function attachHttpMocks(page, httpMocks) {
       body: "[]",
     });
   });
+
+  return observer;
 }
 
 
@@ -222,8 +423,13 @@ module.exports = {
   matchPath,
   matchQuerySpec,
   findHttpMock,
+  findHttpMockEntry,
   mockedTargets,
   requestTargetsMock,
+  originOf,
+  createMockUsageTally,
+  createRequestInventory,
+  createMockObserver,
   attachHttpMocks,
   isDeclaredErrorMock,
   unmockedRouteFrom,