fix(docs): surface SDK diffs in js-libs-update workflow PRs (#46742)

Two-part fix for the Update JS Client Libraries Docs workflow. First,
the `make` invocation was narrowed to `make download.tsdoc.v2` so the
workflow no longer re-downloads unrelated Management and Storage REST
openapi specs alongside the JS TypeDoc files, which was the source of
the noise in #46738. Second, the `build-reference-content` snapshot test
now serializes to a JSON file via `toMatchFileSnapshot` with a
cycle-breaker, because the previous `toMatchSnapshot` of a raw object
was being collapsed to `[Object]` placeholders by pretty-format (533 of
them), hiding every param rename, JSDoc edit, return-type change, and
signature tweak. Verified against supabase-js v2.108.0: the `count` to
`rows` rename in `PostgrestTransformBuilder.{limit,maxAffected}` now
shows up in the snapshot diff as expected.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Updated documentation generation workflow to run a more targeted build
command.
* Added ignore rule for test snapshot files and refreshed the
autogenerated PR description/reference snapshot.

* **Tests**
* Improved test snapshot strategy to use file-based snapshots and robust
handling of circular structures for more reliable assertions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

.github/workflows/docs-js-libs-update.yml

@@ -50,7 +50,7 @@ jobs:
           echo "Regenerating tsdoc files for JS client libraries..."
           echo "Source: ${SOURCE}"
           echo "Version: ${VERSION}"
-          make
+          make download.tsdoc.v2
 
       - name: Refresh reference-content snapshot
         working-directory: apps/docs
@@ -74,7 +74,7 @@ jobs:
           title: 'docs: update js sdk docs (${{ github.event.inputs.version }})'
           body: |
             Updates JS sdk documentation following stable release.
-            Ran `make` in apps/docs/spec to regenerate tsdoc files.
+            Ran `make download.tsdoc.v2` in apps/docs/spec and refreshed the reference-content snapshot.
 
             **Details:**
             - **Version:** `${{ github.event.inputs.version }}`

.prettierignore

@@ -31,3 +31,5 @@ apps/**/.contentlayer
 packages/ui/src/components/Form/examples/PhoneProvidersSchema.json
 # ignore because of <br/><br/>
 apps/www/_blog/2025-07-14-supabase-ui-platform-kit.mdx
+# vitest file snapshots — JSON.stringify owns the format, not Prettier
+apps/docs/scripts/__snapshots__/

apps/docs/scripts/build-reference-content.test.ts

@@ -10,6 +10,11 @@ import { collectReferenceContent } from './build-reference-content'
  * sees. When the supabase-js `make` workflow lands a new release in
  * `spec/reference/javascript/v2/`, re-run with `--update` to refresh the
  * baseline as part of the same PR.
+ *
+ * Serializes to a JSON string first so vitest's `pretty-format` serializer
+ * doesn't collapse deep / cyclic structures (typeSpec contains
+ * self-referencing builder types) into `[Object]` placeholders — which would
+ * make param renames, signature changes, and JSDoc edits invisible.
  */
 describe('build-reference-content — javascript/v2', () => {
   it('matches snapshot', async () => {
@@ -17,6 +22,15 @@ describe('build-reference-content — javascript/v2', () => {
       'javascript',
       'v2'
     )
-    expect({ bySlug, flat, sections, functionsList, typeSpec }).toMatchSnapshot()
+    const seen = new WeakSet<object>()
+    const breakCycles = (_key: string, value: unknown) => {
+      if (value && typeof value === 'object') {
+        if (seen.has(value as object)) return '[Circular]'
+        seen.add(value as object)
+      }
+      return value
+    }
+    const json = JSON.stringify({ bySlug, flat, sections, functionsList, typeSpec }, breakCycles, 2)
+    await expect(json).toMatchFileSnapshot('./__snapshots__/build-reference-content.v2.json')
   })
 })