Add script to include example URLs in JSDocs for index.d.ts

- Created add-examples-to-dts.ts script that runs after build
- Script imports index.ts to populate test data
- Extracts example URLs using getTests from collector.ts
- Adds @example JSDoc comments to each exported function in index.d.ts
- Updated build script to run the new script after TypeScript compilation

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

Author: Copilot

add-examples-to-dts.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+import {readFileSync, writeFileSync} from 'node:fs';
+// Import index.ts first to populate the test data
+import './index.ts';
+import {getTests} from './collector.ts';
+
+// Read the generated .d.ts file
+const dtsPath = './distribution/index.d.ts';
+const dtsContent = readFileSync(dtsPath, 'utf8');
+
+// Process each exported function
+const lines = dtsContent.split('\n');
+const outputLines: string[] = [];
+
+for (let i = 0; i < lines.length; i++) {
+	const line = lines[i];
+	
+	// Check if this is a function declaration
+	const match = line.match(/^export declare const (\w+):/);
+	if (match) {
+		const functionName = match[1];
+		
+		// Get the tests/examples for this function
+		const examples = getTests(functionName);
+		
+		// Only add examples if they exist and aren't just references to other functions
+		if (examples && examples.length > 0 && examples[0] !== 'combinedTestOnly') {
+			// Filter to only include actual URLs (not references to other functions)
+			const urlExamples = examples.filter(url => url.startsWith('http'));
+			
+			if (urlExamples.length > 0) {
+				// Add JSDoc comment with examples before the declaration
+				outputLines.push('/**');
+				for (const url of urlExamples) {
+					outputLines.push(` * @example ${url}`);
+				}
+				outputLines.push(' */');
+			}
+		}
+	}
+	
+	outputLines.push(line);
+}
+
+// Write the modified content back
+writeFileSync(dtsPath, outputLines.join('\n'), 'utf8');
+
+console.log('✓ Added example URLs to index.d.ts');

package.json

@@ -24,7 +24,7 @@
 		"distribution/index.d.ts"
 	],
 	"scripts": {
-		"build": "run-p build:*",
+		"build": "run-p build:esbuild build:typescript build:demo && npx tsx add-examples-to-dts.ts",
 		"build:esbuild": "esbuild index.ts --bundle --external:github-reserved-names --outdir=distribution --format=esm --drop-labels=TEST",
 		"build:typescript": "tsc --declaration --emitDeclarationOnly",
 		"build:demo": "vite build demo",