valaxy-addon-typedoc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 云游君 YunYouJun <me@yunyoujun.cn>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# valaxy-addon-typedoc
+
+Generate TypeScript API reference pages inside a Valaxy site. TypeDoc runs on the Node side; Press provides navigation and the normal documentation layout.
+
+This addon requires the generated-content integration in the next Valaxy release. Until that release, use it from this repository's pnpm workspace.
+
+```ts
+import { defineValaxyConfig } from 'valaxy'
+import { addonTypeDoc } from 'valaxy-addon-typedoc'
+
+export default defineValaxyConfig({
+  theme: 'press',
+  addons: [addonTypeDoc({
+    options: './typedoc.json',
+    watch: ['../src/**/*.ts', './tsconfig*.json'],
+    routeBase: '/api/',
+    // Set true when pages/api/index.md provides a handwritten overview.
+    excludeIndex: true,
+  })],
+})
+```
+
+```json
+{
+  "entryPoints": ["../src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json",
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true
+}
+```
+
+`options` and `watch` are relative to the Valaxy site. Paths in TypeDoc's JSON configuration are relative to that configuration file. Use an explicit `tsconfig` to avoid accidentally compiling the documentation app. Include source directories in `watch` so new exports and files trigger regeneration. TypeDoc program dependencies and extended TypeScript configurations are also tracked.
+
+The addon owns the Markdown output settings and writes under `.valaxy/content/pages/`. Do not edit these generated files. The cache fingerprints source contents, configuration, dependency declarations, compiler/plugin versions and Git revision. Remove `.valaxy/content/` to force a clean generation.
+
+In development, changes are debounced and serialized. Ordinary Markdown edits do not run TypeDoc. A failed generation keeps the last successful pages and logs an error. Production generation failures stop the build; a matching cache is valid reuse. Empty references, duplicate routes and collisions with handwritten pages are errors.
+
+The generated Press sidebar is installed only for `routeBase`, preserving other sidebar sections. Set `sidebar: false` to manage navigation yourself. Generated pages use `sharedLocale: true`: one reference URL across interface languages. `themeConfig.apiReference` and each page's `apiSource` contain the source revision, package version when available, and whether the checkout has uncommitted changes.
+
+Keep guides and examples handwritten. An optional `<PressApiIndex :groups="groups" />` provides a category index with client-side filtering; each group has a `title` and `items: { text, link }[]`.
+
+Deploy the resulting site normally. HTTP redirects from a retired API domain must be configured on that domain's host; installing this addon does not change DNS or redirects.

package/README.zh-CN.md

@@ -0,0 +1,43 @@
+# valaxy-addon-typedoc
+
+在 Valaxy 站内生成 TypeScript API 参考文档。TypeDoc 仅在 Node 侧运行，Press 提供导航和文档布局。
+
+本插件依赖下一版 Valaxy 的生成内容集成能力。该版本发布前，请在本仓库的 pnpm workspace 中使用。
+
+```ts
+import { defineValaxyConfig } from 'valaxy'
+import { addonTypeDoc } from 'valaxy-addon-typedoc'
+
+export default defineValaxyConfig({
+  theme: 'press',
+  addons: [addonTypeDoc({
+    options: './typedoc.json',
+    watch: ['../src/**/*.ts', './tsconfig*.json'],
+    routeBase: '/api/',
+    // 自己编写 pages/api/index.md 总览时启用。
+    excludeIndex: true,
+  })],
+})
+```
+
+```json
+{
+  "entryPoints": ["../src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json",
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true
+}
+```
+
+`options`、`watch` 相对 Valaxy 站点目录；TypeDoc JSON 中的路径相对该配置文件。请显式指定 `tsconfig`，避免误用文档应用的编译配置。`watch` 应覆盖源码目录，以发现新增文件和导出；插件还会追踪 TypeScript 依赖声明及继承的编译配置。
+
+插件负责 Markdown 输出，生成文件位于 `.valaxy/content/pages/`，不要手动编辑。缓存键包含源码内容、配置、依赖声明、编译器和插件版本、Git 提交。删除 `.valaxy/content/` 可强制重新生成。
+
+开发模式会合并短时间变更并串行生成；普通 Markdown 修改不会触发 TypeDoc。生成失败时保留上次成功页面并输出错误；生产模式直接阻断构建，输入匹配的缓存可正常复用。空文档、重复路由以及与手写页面冲突均会报错。
+
+自动侧栏只写入 `routeBase` 分区，保留其他分区；使用 `sidebar: false` 可自行管理导航。生成页标记 `sharedLocale: true`，切换界面语言保持同一个参考 URL。`themeConfig.apiReference` 和页面的 `apiSource` 提供源码提交、可获取的包版本及未提交修改标记。
+
+使用教程与示例继续手写。可选的 `<PressApiIndex :groups="groups" />` 提供分类和即时筛选；每组包含 `title` 和 `items: { text, link }[]`。
+
+按普通 Valaxy 站点部署即可。旧 API 域名的 HTTP 重定向需在旧域名的托管平台配置，安装插件不会修改 DNS 或重定向。

package/index.ts

@@ -0,0 +1,2 @@
+export { addonTypeDoc } from './node'
+export type { TypeDocAddonOptions } from './node'

package/node/index.ts

@@ -0,0 +1,73 @@
+import type { ContentLoaderContext } from 'valaxy'
+import type { Plugin } from 'vite'
+import { defineValaxyAddon, loadAllContent } from 'valaxy'
+import { createTypeDocLoader } from './loader'
+
+export interface TypeDocAddonOptions {
+  /** TypeDoc JSON configuration, relative to the Valaxy project. */
+  options: string
+  /** Source/configuration globs relative to the Valaxy project, used for cache invalidation and watching. */
+  watch: string[]
+  /** URL directory for generated reference pages. @default '/api/' */
+  routeBase?: string
+  /** Keep a handwritten landing page at routeBase. @default false */
+  excludeIndex?: boolean
+  /** Add the generated navigation to Press sidebars. @default true */
+  sidebar?: boolean
+}
+
+export const addonTypeDoc = defineValaxyAddon<TypeDocAddonOptions>((settings) => {
+  if (!settings?.options || !settings.watch?.length)
+    throw new Error('[typedoc] An options file and source watch globs are required.')
+  return {
+    name: 'valaxy-addon-typedoc',
+    options: settings,
+    setup(node) {
+      const loader = createTypeDocLoader(settings, node.options.userRoot)
+      node.options.config.loaders ??= []
+      node.options.config.loaders.push(loader)
+      const plugin: Plugin = {
+        name: 'valaxy-addon-typedoc:watch',
+        apply: 'serve',
+        async configureServer(server) {
+          const ctx: ContentLoaderContext = { node, cacheDir: `${node.options.tempDir}/content`, mode: 'dev' }
+          let closed = false
+          let timer: ReturnType<typeof setTimeout> | undefined
+          let pending = Promise.resolve()
+          const update = () => {
+            clearTimeout(timer)
+            timer = setTimeout(() => {
+              pending = pending.then(async () => {
+                if (closed)
+                  return
+                await node.hooks.callHook('content:before-load')
+                await loadAllContent([loader], ctx)
+                await node.hooks.callHook('content:loaded')
+                server.watcher.add(await loader.watchPaths())
+                const config = server.moduleGraph.getModuleById('/@valaxyjs/config')
+                if (config)
+                  server.moduleGraph.invalidateModule(config)
+                // Added/deleted routes and navigation must become visible together.
+                server.ws.send({ type: 'full-reload' })
+              }).catch(error => server.config.logger.error(`[typedoc] ${error}`))
+            }, 200)
+          }
+          const change = (file: string) => {
+            if (loader.isSource(file))
+              update()
+          }
+          server.watcher.add(await loader.watchPaths())
+          server.watcher.on('add', change).on('change', change).on('unlink', change)
+          server.httpServer?.once('close', () => {
+            closed = true
+            clearTimeout(timer)
+            server.watcher.off('add', change).off('change', change).off('unlink', change)
+          })
+        },
+      }
+      node.options.config.vite ??= {}
+      node.options.config.vite.plugins ??= []
+      node.options.config.vite.plugins.push(plugin)
+    },
+  }
+})

package/node/links.ts

@@ -0,0 +1,14 @@
+/** Reconcile TypeDoc inheritance links with the Markdown plugin's HTML anchors. */
+export function resolveSymbolAnchors(markdown: string, anchors: Map<string, Set<string>>) {
+  // Preserve fenced examples and inline code verbatim.
+  return markdown.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~|`+[^`]*`+)/g).map((part, index) => {
+    if (index % 2)
+      return part
+    return part.replace(/\]\((\/[^\s)]*\.md)#([^\s)]+)\)/g, (link, page: string, hash: string) => {
+      const symbol = `api-${decodeURIComponent(hash)}`
+      return anchors.get(decodeURIComponent(page))?.has(symbol)
+        ? `](${page}#${encodeURIComponent(symbol)})`
+        : link
+    })
+  }).join('')
+}

package/node/loader.ts

@@ -0,0 +1,207 @@
+import type { ContentItem, ContentLoader, ContentLoaderContext } from 'valaxy'
+import type { TypeDocAddonOptions } from './index'
+import { execFileSync, spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { dirname, relative, resolve, sep } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import fg from 'fast-glob'
+import fs from 'fs-extra'
+import { minimatch } from 'minimatch'
+import { resolveSymbolAnchors } from './links'
+
+interface NavigationItem {
+  title: string
+  path?: string | null
+  children?: NavigationItem[]
+}
+
+interface SidebarItem {
+  text: string
+  link?: string
+  collapsed?: boolean
+  items?: SidebarItem[]
+}
+
+interface Cache {
+  key: string
+  files: string[]
+  items: ContentItem[]
+  navigation: NavigationItem[]
+  source: { revision: string, dirty: boolean, version?: string }
+}
+
+const require = createRequire(import.meta.url)
+
+export function createTypeDocLoader(settings: TypeDocAddonOptions, userRoot: string) {
+  const optionsFile = resolve(userRoot, settings.options)
+  const routeBase = `/${(settings.routeBase || '/api/').replace(/^\/+|\/+$/g, '')}/`
+  if (routeBase.includes('..') || routeBase.includes('\\') || routeBase.includes('#') || routeBase.includes('?'))
+    throw new Error('[typedoc] routeBase must be an absolute URL directory without traversal.')
+  const watchedRoots = settings.watch.filter(pattern => !pattern.startsWith('!')).map(pattern => resolve(userRoot, pattern.split(/[*?{[]/)[0]))
+  let dependencies: string[] = []
+  let navigation: NavigationItem[] = []
+  let source: Cache['source'] = { revision: 'unversioned', dirty: false }
+  let runs = 0
+
+  async function sourceFiles() {
+    const sources = await fg(settings.watch, { cwd: userRoot, absolute: true, onlyFiles: true, ignore: ['**/.valaxy/**', '**/dist/**'] })
+    return [...new Set([optionsFile, ...sources, ...dependencies])].sort()
+  }
+
+  async function fingerprint(files: string[]) {
+    const hash = createHash('sha256').update(JSON.stringify({ schema: 8, settings }))
+    for (const pkg of ['valaxy-addon-typedoc', 'typedoc', 'typedoc-plugin-markdown', 'typescript']) {
+      let directory = dirname(require.resolve(pkg))
+      while (directory !== dirname(directory)) {
+        const metadata = await fs.readJson(resolve(directory, 'package.json')).catch(() => undefined)
+        if (metadata?.name === pkg) {
+          hash.update(JSON.stringify(metadata))
+          break
+        }
+        directory = dirname(directory)
+      }
+    }
+    // Source links generated by TypeDoc point at this exact revision.
+    try {
+      source.revision = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: userRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+      source.dirty = !!execFileSync('git', ['status', '--porcelain'], { cwd: userRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+      hash.update(JSON.stringify({ revision: source.revision, dirty: source.dirty }))
+    }
+    catch { hash.update('unversioned') }
+    for (const file of files) {
+      hash.update(file)
+      hash.update(await fs.readFile(file).catch(() => 'missing'))
+    }
+    return hash.digest('hex')
+  }
+
+  const toSidebar = (items: NavigationItem[]): SidebarItem[] => items.map(item => ({
+    text: item.title,
+    ...(item.path ? { link: `${routeBase}${item.path.replace(/(^|\/)index\.md$/, '$1').replace(/\.md(?=#|$)/, '')}` } : {}),
+    ...(item.children?.length ? { collapsed: true, items: toSidebar(item.children) } : {}),
+  }))
+
+  const loader: ContentLoader & { sourceFiles: typeof sourceFiles, watchPaths: () => Promise<string[]>, isSource: (file: string) => boolean, generationCount: () => number } = {
+    name: `typedoc-${routeBase.replaceAll('/', '-')}`,
+    strict: true,
+    sourceFiles,
+    watchPaths: async () => [...new Set([...watchedRoots, ...await sourceFiles()])],
+    generationCount: () => runs,
+    isSource(file) {
+      const path = relative(userRoot, file).replaceAll('\\', '/')
+      if (/(?:^|\/)\.valaxy\/|(?:^|\/)dist\//.test(path))
+        return false
+      const excluded = settings.watch.filter(pattern => pattern.startsWith('!'))
+      const included = settings.watch.filter(pattern => !pattern.startsWith('!'))
+      return file === optionsFile || dependencies.includes(file)
+        || (included.some(pattern => minimatch(path, pattern, { dot: true }))
+          && !excluded.some(pattern => minimatch(path, pattern.slice(1), { dot: true })))
+    },
+    async load(ctx) {
+      const cacheRoot = resolve(ctx.cacheDir, loader.name)
+      const manifest = resolve(cacheRoot, 'cache.json')
+      const previous = await fs.readJson(manifest).catch(() => undefined) as Cache | undefined
+      dependencies = previous?.files || []
+      const files = await sourceFiles()
+      const key = await fingerprint(files)
+      if (previous?.key === key && previous.items.length) {
+        navigation = previous.navigation
+        source = previous.source
+        return previous.items
+      }
+
+      const started = performance.now()
+      const output = resolve(cacheRoot, 'staging')
+      await fs.ensureDir(output)
+      const resultFile = resolve(cacheRoot, 'worker-result.json')
+      runs++
+      await new Promise<void>((accept, reject) => {
+        const child = spawn(process.execPath, [
+          fileURLToPath(new URL('./worker.mjs', import.meta.url)),
+          optionsFile,
+          output,
+          resolve(cacheRoot, 'navigation.json'),
+          resultFile,
+          routeBase,
+        ], { cwd: userRoot, stdio: ['ignore', 'pipe', 'pipe'] })
+        let diagnostics = ''
+        child.stdout.on('data', chunk => process.stdout.write(chunk))
+        child.stderr.on('data', (chunk) => {
+          diagnostics = (diagnostics + String(chunk)).slice(-8000)
+          process.stderr.write(chunk)
+        })
+        child.once('error', reject)
+        child.once('close', code => code === 0 ? accept() : reject(new Error(`[typedoc] Generation failed (${code}). ${diagnostics}`)))
+      })
+      const result = await fs.readJson(resultFile) as { files: string[], version?: string }
+      dependencies = result.files
+      source.version = result.version
+      const paths = await fg('**/*.md', { cwd: output })
+      if (!paths.length)
+        throw new Error('[typedoc] Refusing to publish empty API documentation.')
+      const sources = new Map(await Promise.all(paths.map(async page => [page, await fs.readFile(resolve(output, page), 'utf8')] as const)))
+      const anchors = new Map([...sources].map(([page, markdown]) => [
+        `${routeBase}${page}`,
+        new Set([...markdown.matchAll(/<a id="([^"]+)"><\/a>/g)].map(match => match[1])),
+      ]))
+      const items: ContentItem[] = []
+      for (const page of paths.sort()) {
+        if (settings.excludeIndex && page === 'index.md')
+          continue
+        const markdown = resolveSymbolAnchors(sources.get(page)!, anchors)
+        const title = markdown.match(/^# (.+?)(?: \{#.*\})?$/m)?.[1] || page
+        const revision = `${source.version ? `${source.version} · ` : ''}${source.revision.slice(0, 12)}${source.dirty ? ' (uncommitted changes)' : ''}`
+        const body = markdown.replace(/^(# .+\n)/m, `$1\n> Source: ${revision}\n`)
+        const canonical = `${routeBase}${page.replace(/(^|\/)index\.md$/, '$1').replace(/\.md$/, '')}`
+        const content = `---\ncanonical: ${JSON.stringify(canonical)}\ntitle: ${JSON.stringify(title)}\npageTitle: false\napi: true\napiSource: ${JSON.stringify(source)}\nsharedLocale: true\neditLink: false\nlastUpdated: false\n---\n\n${body}`
+        items.push({ path: `${routeBase.slice(1)}${page}`, content })
+      }
+      if (!items.length)
+        throw new Error('[typedoc] Refusing to replace references with an empty page set.')
+      navigation = await fs.readJson(resolve(cacheRoot, 'navigation.json'))
+      // Include parent project configuration and package metadata in dependency invalidation.
+      const checkedDirectories = new Set<string>()
+      for (const file of [...dependencies, optionsFile]) {
+        let directory = dirname(file)
+        while (directory !== dirname(directory) && !checkedDirectories.has(directory)) {
+          checkedDirectories.add(directory)
+          if (!directory.includes(`${sep}node_modules${sep}`)) {
+            for (const name of ['tsconfig.json', 'package.json', 'pnpm-lock.yaml']) {
+              const config = resolve(directory, name)
+              if (await fs.pathExists(config))
+                dependencies.push(config)
+            }
+          }
+          directory = dirname(directory)
+        }
+      }
+      dependencies = [...new Set(dependencies)]
+      if (await fingerprint(files) !== key)
+        throw new Error('[typedoc] Inputs changed during generation; previous pages were preserved. Retry the build.')
+      const finalFiles = await sourceFiles()
+      const next: Cache = { key: await fingerprint(finalFiles), files: finalFiles, items, navigation, source }
+      await fs.writeJson(`${manifest}.tmp`, next)
+      await fs.rename(`${manifest}.tmp`, manifest)
+      process.stdout.write(`[typedoc] Generated ${items.length} pages in ${((performance.now() - started) / 1000).toFixed(2)}s\n`)
+      return items
+    },
+    onLoaded(ctx: ContentLoaderContext) {
+      const theme = ctx.node.options.config.themeConfig as Record<string, any>
+      theme.apiReference = source
+      if (settings.sidebar === false)
+        return
+      const install = (config: Record<string, any>) => {
+        const sidebar = config.sidebar
+        config.sidebar = { ...(Array.isArray(sidebar) ? { '/': sidebar } : sidebar), [routeBase]: toSidebar(navigation) }
+      }
+      install(theme)
+      for (const locale of Object.values(theme.locales || {}) as Record<string, any>[]) {
+        locale.themeConfig ??= {}
+        install(locale.themeConfig)
+      }
+    },
+  }
+  return loader
+}

package/node/worker.mjs

@@ -0,0 +1,63 @@
+import { writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import process from 'node:process'
+import { Application, Converter } from 'typedoc'
+import ts from 'typescript'
+
+async function main() {
+  // A short-lived process releases the compiler's AST before Vite starts bundling.
+  const [options, out, navigationJson, resultFile, publicPath] = process.argv.slice(2)
+  const require = createRequire(import.meta.url)
+  const app = await Application.bootstrapWithPlugins({
+    options,
+    plugin: [require.resolve('typedoc-plugin-markdown')],
+    out,
+    readme: 'none',
+    includeVersion: true,
+    githubPages: false,
+    entryFileName: 'index.md',
+    hidePageHeader: true,
+    hideBreadcrumbs: true,
+    useCodeBlocks: true,
+    // Normal heading IDs remain compatible with the old site. Symbol links use
+    // a separate namespace, avoiding collisions with comment headings.
+    useCustomAnchors: false,
+    useHTMLAnchors: true,
+    anchorPrefix: 'api-',
+    navigationJson,
+    publicPath,
+  })
+  const files = new Set()
+  app.converter.on(Converter.EVENT_BEGIN, (context) => {
+    for (const program of context.programs) {
+      for (const file of program.getSourceFiles())
+        files.add(file.fileName)
+    }
+  })
+  const tsconfig = app.options.getValue('tsconfig')
+  if (tsconfig) {
+    ts.getParsedCommandLineOfConfigFile(tsconfig, {}, {
+      ...ts.sys,
+      readFile(file) {
+        files.add(file)
+        return ts.sys.readFile(file)
+      },
+      onUnRecoverableConfigFileDiagnostic: diagnostic => app.logger.error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')),
+    })
+  }
+  const project = await app.convert()
+  if (!project || app.logger.hasErrors())
+    throw new Error('[typedoc] TypeScript conversion failed; previous pages were preserved.')
+  app.validate(project)
+  if (app.logger.hasErrors())
+    throw new Error('[typedoc] Reference validation failed.')
+  await app.generateOutputs(project)
+  if (app.logger.hasErrors())
+    throw new Error('[typedoc] Markdown generation failed.')
+  await writeFile(resultFile, JSON.stringify({ files: [...files], version: project.packageVersion }))
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "valaxy-addon-typedoc",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Cached TypeDoc reference pages for Valaxy documentation sites",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YunYouJun/valaxy.git",
+    "directory": "packages/valaxy-addon-typedoc"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./node": "./node/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "README.zh-CN.md",
+    "index.ts",
+    "node"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "valaxy": ">=1.0.0-rc.13 <2"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.4.0",
+    "minimatch": "^10.2.4",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.13.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "valaxy": "1.0.0-rc.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}