feat: docgen (#5)

package.json

@@ -14,6 +14,7 @@
     "format": "biome format . --write",
     "lint": "biome lint . --apply-unsafe",
     "playground": "pnpm --filter playgrounds/default dev",
+    "preconstruct": "bun run scripts/preconstruct.ts",
     "prepare": "simple-git-hooks && pnpm build",
     "typecheck": "tsc --noEmit"
   },
@@ -29,6 +30,7 @@
     "@types/react-dom": "^18.2.13",
     "@types/react-helmet": "^6.1.7",
     "@types/serve-static": "^1.15.3",
+    "bun": "^1.0.14",
     "bun-types": "^1.0.6",
     "fs-extra": "^11.1.1",
     "globby": "^13.2.2",

scripts/preconstruct.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { glob } from 'glob'
+
+// Symlinks package sources to dist for local development
+
+console.log('Setting up packages for development.')
+
+// Get all package.json files
+const packagePaths = await glob('**/package.json', {
+  ignore: ['**/dist/**', '**/node_modules/**'],
+})
+
+let count = 0
+for (const packagePath of packagePaths) {
+  type Package = {
+    bin?: Record<string, string> | undefined
+    exports?: Record<string, { types: string; default: string } | string> | undefined
+    name?: string | undefined
+    private?: boolean | undefined
+  }
+  const file = Bun.file(packagePath)
+  const packageJson = (await file.json()) as Package
+
+  // Skip private packages
+  if (packageJson.private) continue
+  if (!packageJson.exports) continue
+
+  count += 1
+  console.log(`${packageJson.name} — ${path.dirname(packagePath)}`)
+
+  const dir = path.resolve(path.dirname(packagePath))
+
+  // Empty dist directory
+  const distDirName = '_lib'
+  const dist = path.resolve(dir, distDirName)
+  let files: string[] = []
+  try {
+    files = await fs.readdir(dist)
+  } catch {
+    await fs.mkdir(dist)
+  }
+
+  const promises = []
+  for (const file of files) {
+    promises.push(fs.rm(path.join(dist, file), { recursive: true, force: true }))
+  }
+  await Promise.all(promises)
+
+  // Link exports to dist locations
+  for (const [key, exports] of Object.entries(packageJson.exports)) {
+    // Skip `package.json` exports
+    if (/package\.json$/.test(key)) continue
+
+    let entries
+    if (typeof exports === 'string')
+      entries = [
+        ['default', exports],
+        ['types', exports.replace('.js', '.d.ts')],
+      ]
+    else entries = Object.entries(exports)
+
+    // Link exports to dist locations
+    for (const [, value] of entries as [type: 'types' | 'default', value: string][]) {
+      const srcDir = path.resolve(dir, path.dirname(value).replace(distDirName, ''))
+      let srcFileName: string
+      if (key === '.') srcFileName = 'index.ts'
+      else srcFileName = path.basename(`${key}.ts`)
+      const srcFilePath = path.resolve(srcDir, srcFileName)
+
+      const distDir = path.resolve(dir, path.dirname(value))
+      const distFileName = path.basename(value)
+      const distFilePath = path.resolve(distDir, distFileName)
+
+      await fs.mkdir(distDir, { recursive: true })
+
+      // Symlink src to dist file
+      await fs.symlink(srcFilePath, distFilePath, 'file')
+    }
+  }
+}
+
+console.log(`Done. Set up ${count} ${count === 1 ? 'package' : 'packages'}.`)

site/pages/hello.mdx

@@ -0,0 +1,19 @@
+import { Docgen } from 'vocs/components'
+
+# Hello [Returns greeting message for name.]
+
+## Import
+
+```ts
+import { hello } from 'hello'
+```
+
+## Usage
+
+```ts
+import { hello } from 'hello'
+
+const message = hello({ name: 'World' })
+```
+
+<Docgen path="src/hello.ts" />