From 8fb08f1c8ee5acb67dc8fc93431dd9aa15e2c30c Mon Sep 17 00:00:00 2001 From: Vanilagy <1696106+Vanilagy@users.noreply.github.com> Date: Fri, 12 Sep 2025 17:16:12 +0200 Subject: [PATCH] Fix missing @group tag, add doc generation validation to build script --- build.sh | 3 ++ package-lock.json | 12 ++++---- package.json | 2 +- packages/mp3-encoder/package.json | 2 +- scripts/generate-api-docs.ts | 51 +++++++++++++++++++++---------- src/sample.ts | 1 + 6 files changed, 47 insertions(+), 24 deletions(-) diff --git a/build.sh b/build.sh index 7084915..e1d5e58 100755 --- a/build.sh +++ b/build.sh @@ -29,6 +29,9 @@ api-extractor run -c packages/mp3-encoder/api-extractor.json tsx scripts/check-docblocks.ts dist/mediabunny.d.ts tsx scripts/check-docblocks.ts packages/mp3-encoder/dist/mediabunny-mp3-encoder.d.ts +# Checks that API docs are generatable +npm run docs:generate -- --dry + # Appends stuff to the declaration files to register the global variables these libraries expose echo 'export as namespace Mediabunny;' >> dist/mediabunny.d.ts echo 'export as namespace MediabunnyMp3Encoder;' >> packages/mp3-encoder/dist/mediabunny-mp3-encoder.d.ts \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 87d97d8..1f86d23 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "mediabunny", - "version": "1.15.0", + "version": "1.15.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "mediabunny", - "version": "1.15.0", + "version": "1.15.1", "license": "MPL-2.0", "workspaces": [ "packages/*" @@ -7749,9 +7749,9 @@ } }, "node_modules/mediabunny": { - "version": "1.14.4", - "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.14.4.tgz", - "integrity": "sha512-WXY384sVkUOGKF2OuQgLqo8+dwX1MLYnpkSDoaPa+oNed4tP4L5u0/Vq0yZQEmcaBO7rRFusMDSBcbrp66R++A==", + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.15.0.tgz", + "integrity": "sha512-yeqr+4sRNzl7QqeHckr+SgPKfaQwSSmhTdVSgKgbenneC+TFlBrk+zCRhF9b7kwLtrm6qziJc/flqYQccX6W/Q==", "license": "MPL-2.0", "peer": true, "workspaces": [ @@ -12242,7 +12242,7 @@ }, "packages/mp3-encoder": { "name": "@mediabunny/mp3-encoder", - "version": "1.15.0", + "version": "1.15.1", "license": "MPL-2.0", "devDependencies": { "@types/emscripten": "^1.40.1" diff --git a/package.json b/package.json index 3ecca8c..ce2e3fe 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "mediabunny", "author": "Vanilagy", - "version": "1.15.0", + "version": "1.15.1", "description": "Pure TypeScript media toolkit for reading, writing, and converting media files, directly in the browser.", "type": "module", "workspaces": [ diff --git a/packages/mp3-encoder/package.json b/packages/mp3-encoder/package.json index 47290fe..638e9a7 100644 --- a/packages/mp3-encoder/package.json +++ b/packages/mp3-encoder/package.json @@ -1,7 +1,7 @@ { "name": "@mediabunny/mp3-encoder", "author": "Vanilagy", - "version": "1.15.0", + "version": "1.15.1", "description": "MP3 encoder extension for Mediabunny, based on LAME.", "main": "./dist/bundles/mediabunny-mp3-encoder.mjs", "module": "./dist/bundles/mediabunny-mp3-encoder.mjs", diff --git a/scripts/generate-api-docs.ts b/scripts/generate-api-docs.ts index 392a61f..14ee916 100644 --- a/scripts/generate-api-docs.ts +++ b/scripts/generate-api-docs.ts @@ -16,7 +16,7 @@ import * as ts from 'typescript'; import * as fs from 'fs'; import * as path from 'path'; -const generateDocs = (entryFiles: string[], apiConfigFile: string) => { +const generateDocs = (entryFiles: string[], apiConfigFile: string, dry = false) => { const program = ts.createProgram(entryFiles, { target: ts.ScriptTarget.ES2020, module: ts.ModuleKind.ESNext, @@ -55,11 +55,13 @@ const generateDocs = (entryFiles: string[], apiConfigFile: string) => { delete groupConfig['heading']; delete groupConfig['intro']; - // Clear and recreate output directory - if (fs.existsSync(outputDir)) { - fs.rmSync(outputDir, { recursive: true }); + // Clear and recreate output directory (skip if dry run) + if (!dry) { + if (fs.existsSync(outputDir)) { + fs.rmSync(outputDir, { recursive: true }); + } + fs.mkdirSync(outputDir, { recursive: true }); } - fs.mkdirSync(outputDir, { recursive: true }); // Collect all exported types for cross-referencing const exportedTypes = new Set(); @@ -1539,9 +1541,11 @@ const generateDocs = (entryFiles: string[], apiConfigFile: string) => { } const finalMarkdown = markdown.replace('', usedByMarkdown); - const outputPath = path.join(outputDir, `${symbolName}.md`); - fs.writeFileSync(outputPath, finalMarkdown); - console.log(`Generated: ${outputPath}`); + if (!dry) { + const outputPath = path.join(outputDir, `${symbolName}.md`); + fs.writeFileSync(outputPath, finalMarkdown); + console.log(`Generated: ${outputPath}`); + } }); // Generate index.md with all exported symbols grouped by group @@ -1587,9 +1591,11 @@ const generateDocs = (entryFiles: string[], apiConfigFile: string) => { indexMarkdown += '\n'; }); - const indexPath = path.join(outputDir, 'index.md'); - fs.writeFileSync(indexPath, indexMarkdown); - console.log(`Generated: ${indexPath}`); + if (!dry) { + const indexPath = path.join(outputDir, 'index.md'); + fs.writeFileSync(indexPath, indexMarkdown); + console.log(`Generated: ${indexPath}`); + } // Generate index.json with sidebar config structure const sidebarConfig = sortedGroups.map((group) => { @@ -1607,15 +1613,28 @@ const generateDocs = (entryFiles: string[], apiConfigFile: string) => { }; }); - const jsonPath = path.join(outputDir, 'index.json'); - fs.writeFileSync(jsonPath, JSON.stringify(sidebarConfig, null, 2)); - console.log(`Generated: ${jsonPath}`); + if (!dry) { + const jsonPath = path.join(outputDir, 'index.json'); + fs.writeFileSync(jsonPath, JSON.stringify(sidebarConfig, null, 2)); + console.log(`Generated: ${jsonPath}`); + } }; const main = () => { const args = process.argv.slice(2); + + // Check for --dry flag + const dryIndex = args.indexOf('--dry'); + const dry = dryIndex !== -1; + + // Remove --dry flag from args + if (dry) { + args.splice(dryIndex, 1); + } + if (args.length < 2) { - console.error('Usage: npm run generate-docs [entry-file2 ...] '); + console.error('Usage: npm run generate-docs [--dry] [entry-file2 ...] '); + console.error(' --dry: Check if docs are generatable without writing files'); console.error(' entry-files: One or more TypeScript entry files'); console.error(' api-config-file: JSON config file defining groups'); process.exit(1); @@ -1625,7 +1644,7 @@ const main = () => { const apiConfigFile = args[args.length - 1]!; const entryFiles = args.slice(0, -1); - generateDocs(entryFiles, apiConfigFile); + generateDocs(entryFiles, apiConfigFile, dry); }; main(); diff --git a/src/sample.ts b/src/sample.ts index a9fd911..285fea2 100644 --- a/src/sample.ts +++ b/src/sample.ts @@ -731,6 +731,7 @@ const isVideoFrame = (x: unknown): x is VideoFrame => { /** * Specifies the rectangular cropping region. + * @group Miscellaneous * @public */ export type CropRectangle = {