mirror of
https://github.com/supabase/supabase.git
synced 2026-09-06 18:11:51 +08:00
833d3cb1d7
## What Routes the **Dart/Flutter v2** reference through the new reference-content pipeline (`scripts/build-reference-content.ts` + `spec/reference/dart/v2/`), the same one JavaScript v2 already uses. Dart v1 stays on the legacy YAML pipeline. ## How Dart has no upstream TypeDoc dump, so this follows the reference README's "adapt other formats as a pre-step" approach: - **`scripts/generate-dart-reference.ts`** converts the committed legacy spec (`spec/supabase_dart_v2.yml`) plus the shared section tree into a TypeDoc-shaped dump at `spec/reference/dart/v2/supabase_flutter.json` (gitignored, like every other dump). Each Dart method becomes a `variant: 'declaration'` node tagged with `@category`/`@subcategory` and carries the legacy function shape (description, notes, params, examples) on a non-TypeDoc `content` field. - **`build-reference-content.ts`** gains a small, backward-compatible addition: it spreads a declaration's `content` straight onto the `functions.json` entry. The renderer then shows params/examples/notes exactly as the legacy YAML did, with no typeSpec round-trip. The field is absent for real TypeDoc dumps, so **JavaScript output is unchanged** (existing JS snapshot still passes). - `dart-v2` added to `SUPPORTS_NEW_REFERENCE_PROCESS`; the v2 `specFile` is dropped from the nav entry so the legacy generator skips it. - Dart search ingest switched to the new-pipeline loader. - `config.json` + hand-authored partials (intro markdown, `initializing`, and subcategory overviews like `using-filters`, `auth-mfa`) added under `spec/reference/dart/v2/partials/`, mirroring the JS lib. - The dart dump is regenerated in `codegen:references:new` and in CI; a self-contained `dart/v2` snapshot test covers the full YAML → dump → content path. ## Verification - `vitest run scripts/build-reference-content.test.ts` — both JS and Dart snapshots pass. - 112 function sections all resolve to renderable `functions.json` entries (104 methods + 7 subcategory overviews + `initializing`). - `tsc --noEmit` clean for all changed files. - Legacy generator confirmed to skip dart v2 (only `dart.v1.*` regenerated). > Note: the live dev server (which needs the Supabase backend) was not run; verification was done at the data-pipeline level plus parity with the production JS pipeline behavior. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added Dart v2 reference documentation sections, including Installing, Initializing, Filters, Modifiers, Auth Admin, MFA, Passkeys, File Buckets, Introduction, and Upgrade guidance. * Expanded the Dart v2 reference pipeline so Dart API pages are generated from the newer reference content flow. * **Bug Fixes** * Improved Dart reference rendering by preserving legacy descriptions, notes, params, and examples in generated function entries. * Updated Dart v2 reference search to use the new pipeline’s generated content so results and navigation stay in sync. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
77 lines
2.8 KiB
TypeScript
77 lines
2.8 KiB
TypeScript
import { beforeAll, describe, expect, it } from 'vitest'
|
|
|
|
import { collectReferenceContent } from './build-reference-content'
|
|
import { generateDartReferenceDump } from './generate-dart-reference'
|
|
|
|
function serialize(content: {
|
|
bySlug: unknown
|
|
flat: unknown
|
|
sections: unknown
|
|
functionsList: unknown
|
|
typeSpec: unknown
|
|
}): string {
|
|
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 { bySlug, flat, sections, functionsList, typeSpec } = content
|
|
return JSON.stringify({ bySlug, flat, sections, functionsList, typeSpec }, breakCycles, 2)
|
|
}
|
|
|
|
/**
|
|
* Regression guard for the new reference-content pipeline. Snapshots the five
|
|
* derived artifacts produced for `javascript/v2` so that any change in the
|
|
* extraction logic (or in the upstream supabase-js TypeDoc output) shows up
|
|
* as a snapshot diff in CI rather than silently shifting what the renderer
|
|
* 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.
|
|
*
|
|
* ---
|
|
*
|
|
* Update on Jun 30th, 2026. Skipping this until we figure out a better way to
|
|
* avoid downloaded typedoc files to block build on unrelated PRs.
|
|
*/
|
|
describe.skip('build-reference-content: javascript/v2', () => {
|
|
it('matches snapshot', async () => {
|
|
const content = await collectReferenceContent('javascript', 'v2')
|
|
await expect(serialize(content)).toMatchFileSnapshot(
|
|
'./__snapshots__/build-reference-content.v2.json'
|
|
)
|
|
})
|
|
})
|
|
|
|
/**
|
|
* Dart/v2 has no upstream TypeDoc dump; its source is regenerated from the
|
|
* committed `spec/supabase_dart_v2.yml` by `generate-dart-reference.ts`. We run
|
|
* that converter first so the snapshot covers the full conversion + build path
|
|
* (YAML to dump to content) and surfaces any drift in either step.
|
|
*
|
|
* ---
|
|
*
|
|
* Update on Jun 30th, 2026. Skipping this for the same reason as the
|
|
* javascript/v2 suite above, until snapshot updates are decoupled from
|
|
* unrelated builds.
|
|
*/
|
|
describe.skip('build-reference-content: dart/v2', () => {
|
|
beforeAll(async () => {
|
|
await generateDartReferenceDump()
|
|
})
|
|
|
|
it('matches snapshot', async () => {
|
|
const content = await collectReferenceContent('dart', 'v2')
|
|
await expect(serialize(content)).toMatchFileSnapshot(
|
|
'./__snapshots__/build-reference-content.dart.v2.json'
|
|
)
|
|
})
|
|
})
|