From 116f709f99e3873fe9a4b5e35b0cb2a8fb0bbdb1 Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 13 Nov 2025 12:38:04 +0200 Subject: [PATCH] docs: run format --- apps/docs/scripts/CI-INTEGRATION.md | 29 +++++++++++++---- .../docs/scripts/generate-yaml-suggestions.ts | 4 ++- .../scripts/validate-reference-sync.README.md | 31 ++++++++++++++++--- apps/docs/scripts/validate-reference-sync.ts | 26 ++++++---------- 4 files changed, 63 insertions(+), 27 deletions(-) diff --git a/apps/docs/scripts/CI-INTEGRATION.md b/apps/docs/scripts/CI-INTEGRATION.md index 2472c036369..905e835d4c1 100644 --- a/apps/docs/scripts/CI-INTEGRATION.md +++ b/apps/docs/scripts/CI-INTEGRATION.md @@ -7,6 +7,7 @@ The reference sync validation is integrated into the `docs-js-libs-update.yml` w ## Workflow ### 1. Trigger (from supabase-js repo) + ``` supabase-js stable release → triggers docs-js-libs-update.yml ``` @@ -14,29 +15,35 @@ supabase-js stable release → triggers docs-js-libs-update.yml ### 2. Steps in CI 1. **Regenerate TypeDoc files** + ```bash cd apps/docs/spec make # Downloads & transforms latest specs ``` 2. **Run validation** + ```bash cd apps/docs pnpm run validate:references:fix ``` + - Generates `sync-report.json` with all issues - Generates `sync-report-stubs.yaml` with documentation stubs - Exits with error if validation fails (non-blocking) 3. **Generate PR comment** + ```bash pnpm run validate:references:comment ``` + - Reads `sync-report.json` and `sync-report-stubs.yaml` - Formats as markdown with GitHub suggestions - Outputs to temp file for PR comment 4. **Create PR** + - PR is created with regenerated TypeDoc files - Validation comment is posted automatically @@ -49,7 +56,7 @@ supabase-js stable release → triggers docs-js-libs-update.yml ### 3. Example PR Comment -```markdown +````markdown ## 📊 Reference Documentation Sync Report ### Summary @@ -67,9 +74,10 @@ supabase-js stable release → triggers docs-js-libs-update.yml View broken references (6) - `@supabase/auth-js.GoTrueClient.mfa.enroll` -... + ... **Action:** Remove these entries from `spec/supabase_js_v2.yml` + --- @@ -80,7 +88,7 @@ Click **"Commit suggestion"** on each block below. #### VectorBucketApi -```suggestion +````suggestion - id: createbucket title: createBucket $ref: '@supabase/storage-js.index.VectorBucketApi.createBucket' @@ -94,10 +102,12 @@ Click **"Commit suggestion"** on each block below. ```typescript const { data, error } = await client.createBucket('embeddings') ``` -``` +```` +```` 🤖 Auto-generated via `validate-reference-sync.ts` -``` + +```` ## Developer Workflow @@ -150,9 +160,10 @@ Basic validation without stub generation. ```bash pnpm run validate:references -``` +```` ### `validate:references:fix` + Validation + generate documentation stubs. ```bash @@ -160,6 +171,7 @@ pnpm run validate:references:fix ``` ### `validate:references:comment` + Generate GitHub PR comment from validation results. ```bash @@ -176,21 +188,25 @@ pnpm run validate:references:comment ## Troubleshooting **PR comment not appearing?** + - Check workflow logs for "Generate PR comment" step - Ensure `sync-report.json` exists after validation - Verify PR was created successfully **Suggestions not formatting correctly?** + - GitHub requires exact YAML indentation (2 spaces) - Check suggestion blocks start with proper indent - Verify no trailing whitespace **Too many suggestions overwhelming?** + - Suggestions are grouped by class - You can apply them selectively - Or use the stub file directly and copy what you need **Validation failing incorrectly?** + - Check if new API matches naming patterns (`*Client`, `*Api`, etc.) - Warnings won't block CI, only errors - Review classification logic in validation script @@ -198,6 +214,7 @@ pnpm run validate:references:comment ## Future Enhancements Potential improvements: + - Auto-remove broken references (optional flag) - Interactive mode for reviewing suggestions - Batch apply all suggestions at once diff --git a/apps/docs/scripts/generate-yaml-suggestions.ts b/apps/docs/scripts/generate-yaml-suggestions.ts index 0e49e88e67c..6480a930246 100644 --- a/apps/docs/scripts/generate-yaml-suggestions.ts +++ b/apps/docs/scripts/generate-yaml-suggestions.ts @@ -162,7 +162,9 @@ async function generatePRComment( sections.push(`- ❌ **${report.summary.broken_references} broken references** (APIs removed)`) } if (report.summary.missing_documentation > 0) { - const errors = report.issues.filter((i) => i.type === 'missing-documentation' && i.severity === 'error').length + const errors = report.issues.filter( + (i) => i.type === 'missing-documentation' && i.severity === 'error' + ).length sections.push(`- 📝 **${errors} new undocumented APIs** (auto-detected)`) } diff --git a/apps/docs/scripts/validate-reference-sync.README.md b/apps/docs/scripts/validate-reference-sync.README.md index 5c3c3ab1f10..ba48c2ad4dd 100644 --- a/apps/docs/scripts/validate-reference-sync.README.md +++ b/apps/docs/scripts/validate-reference-sync.README.md @@ -5,6 +5,7 @@ This script validates that the documentation YAML files (e.g., `supabase_js_v2.y ## Purpose The documentation system combines two sources: + - **Auto-generated API docs** from TypeDoc (`spec/enrichments/tsdoc_v2/combined.json`) - **Human-written enrichments** in YAML files (`spec/supabase_js_v2.yml`) @@ -30,6 +31,7 @@ pnpm run validate:references ``` This will: + - Validate the sync between `combined.json` and `supabase_js_v2.yml` - Generate a report at `sync-report.json` - Exit with code 1 if issues are found (useful for CI) @@ -41,6 +43,7 @@ pnpm run validate:references:fix ``` This will: + - Run the validation - Generate stub YAML entries for missing documentation at `sync-report-stubs.yaml` - You can then manually add these stubs to your YAML file and fill in descriptions @@ -65,6 +68,7 @@ tsx scripts/validate-reference-sync.ts --fix --strict --report-path output/repor The script **automatically discovers** all classes with public methods. No hardcoded lists to maintain! **How it works:** + 1. Scans `combined.json` for all classes (kind: 128) 2. Checks each class for public methods or constructors 3. Classifies based on patterns and context @@ -72,15 +76,18 @@ The script **automatically discovers** all classes with public methods. No hardc **Classification:** **ERROR severity** (must be documented): + - Classes ending in: `Client`, `Api`, `Builder`, `Channel`, `Scope`, `Manager` - Classes exported from top-level or `index` module - Classes with any existing documentation (proves they're user-facing) **WARNING severity** (review needed): + - Other classes with public methods - Allows manual decision on whether to document **EXCLUDED** (skipped entirely): + - Error classes (name ends with `Error`) - Private/internal methods (starting with `_`) - Protected methods (`isProtected: true`) @@ -88,6 +95,7 @@ The script **automatically discovers** all classes with public methods. No hardc - Classes with `@internal` JSDoc tag **Examples of auto-detected classes:** + - `VectorBucketApi` ✅ (ends with `Api`) - `PostgrestFilterBuilder` ✅ (ends with `Builder`) - `RealtimeChannel` ✅ (ends with `Channel`) @@ -97,12 +105,14 @@ The script **automatically discovers** all classes with public methods. No hardc ### Example issues **Broken reference:** + ``` Reference '@supabase/auth-js.GoTrueClient.mfa.enroll' in YAML does not exist in combined.json. This API may have been removed. ``` **Missing documentation:** + ``` Public API '@supabase/supabase-js.GoTrueClient.getUser' exists in combined.json but is not documented in YAML. @@ -115,6 +125,7 @@ in combined.json but is not documented in YAML. The script extracts descriptions from TypeDoc comments in `combined.json`: **Source (in your code):** + ```typescript /** * Creates a new vector bucket @@ -125,6 +136,7 @@ async createBucket(name: string): Promise ``` **Generated stub:** + ```yaml - id: createbucket title: createBucket @@ -139,7 +151,8 @@ async createBucket(name: string): Promise Examples from `@example` JSDoc tags are also extracted: **Source (in your code):** -```typescript + +````typescript /** * Creates a new vector bucket * @example @@ -150,10 +163,11 @@ Examples from `@example` JSDoc tags are also extracted: * } * ``` */ -``` +```` **Generated stub:** -```yaml + +````yaml - id: createbucket title: createBucket $ref: '@supabase/storage-js.index.VectorBucketApi.createBucket' @@ -168,9 +182,10 @@ Examples from `@example` JSDoc tags are also extracted: console.error('Failed:', error.message) } ``` -``` +```` **Benefits:** + - 🎯 Less manual work - descriptions pulled from source - 📝 Single source of truth - update code comments, stubs auto-update - ✅ Consistency - same descriptions in code and docs @@ -207,6 +222,7 @@ The report is a JSON file with: ``` **Console output** shows statistics: + ``` ✅ Generated 176 stub entries at sync-report-stubs.yaml 📝 150/176 have TypeDoc descriptions @@ -272,6 +288,7 @@ The script parses `combined.json` as a tree and builds a lookup map for these re ### TypeDoc kinds The script checks these TypeDoc node kinds: + - `512`: Constructor - `2048`: Method - `128`: Class (for context) @@ -279,6 +296,7 @@ The script checks these TypeDoc node kinds: ### Public API detection APIs are considered public if they: + - Don't start with `_` - Don't have `isProtected` or `isPrivate` flags - Aren't marked with `@internal` in JSDoc @@ -287,25 +305,30 @@ APIs are considered public if they: ## Troubleshooting **New API not being detected?** + - Check if the class name matches a pattern (`Client`, `Api`, `Builder`, etc.) - If not, it will show as a WARNING - you can still document it - To make it an ERROR, ensure it's exported from top-level or add partial docs **Too many warnings?** + - Warnings are for review - you can ignore non-user-facing classes - Use `--strict` mode in CI only if you want warnings to fail builds - Consider if the warned class should have a documented method (which promotes it to ERROR) **Broken reference for valid API?** + - Check the exact casing and path in `combined.json` - The structure might have changed (e.g., from method to property) - Verify the API still exists in the source code **TypeDoc descriptions not extracted?** + - Check that JSDoc comments are on the method/constructor signature - Ensure comments use `/** */` format (not `//`) - Verify `combined.json` was regenerated after adding comments **Missing legitimate documentation?** + - Add it to the YAML file manually - Or use `--fix` to generate a stub (with TypeDoc content) and fill in the rest diff --git a/apps/docs/scripts/validate-reference-sync.ts b/apps/docs/scripts/validate-reference-sync.ts index d55f8d04555..69d4906b67e 100644 --- a/apps/docs/scripts/validate-reference-sync.ts +++ b/apps/docs/scripts/validate-reference-sync.ts @@ -168,14 +168,7 @@ function isUserFacingClass(className: string): boolean { } // Check for user-facing patterns - const userFacingPatterns = [ - /Client$/, - /Api$/, - /Builder$/, - /Channel$/, - /Scope$/, - /Manager$/, - ] + const userFacingPatterns = [/Client$/, /Api$/, /Builder$/, /Channel$/, /Scope$/, /Manager$/] return userFacingPatterns.some((pattern) => pattern.test(className)) } @@ -296,15 +289,14 @@ function findDocumentableClasses( if (hasPublicMethods) { // Check if this class has any documented methods - const hasDocumentation = node.children?.some((child) => { - const methodPath = [...path, node.name, child.name].join('.') - return yamlRefs.has(methodPath) - }) || false + const hasDocumentation = + node.children?.some((child) => { + const methodPath = [...path, node.name, child.name].join('.') + return yamlRefs.has(methodPath) + }) || false const isUserFacing = - isUserFacingClass(node.name) || - isTopLevelExport(currentPath) || - hasDocumentation + isUserFacingClass(node.name) || isTopLevelExport(currentPath) || hasDocumentation classes.set(currentPath, { className: node.name, @@ -362,7 +354,9 @@ function validateMissingDocumentation( // Find the parent class for this method const parts = path.split('.') let parentClassPath: string | null = null - let parentClassInfo: { className: string; hasDocumentation: boolean; isUserFacing: boolean } | undefined + let parentClassInfo: + | { className: string; hasDocumentation: boolean; isUserFacing: boolean } + | undefined // Try to find parent class by removing last segment (the method name) for (let i = parts.length - 1; i >= 2; i--) {