build(typedoc): harden gate and propagate CLI exit code

* typedoc.mjs: forward CLI args via execFileSync, propagate typedoc exit
  status, and guarantee docs/*.md restoration via try/finally on failure.
* typedoc.json: enable treatWarningsAsErrors and excludeInternal; map
  EventEmitter.defaultMaxListeners to nodejs.org docs.
* tsconfig.json: scope types to ["node"] to fix the TS2591 errors that
  typedoc surfaces under TypeScript 6.x stricter implicit type
  acquisition rules.

Extracted from PR #3211 as an atomic build/typedoc precursor.

diff --git a/tsconfig.json b/tsconfig.json
index b07e79437d1148946e6a1e864c049f222d3f35af..6564c98b0a7355b1141cf3df4eecf2a36a7b6293 100644 (file)
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -4,6 +4,7 @@
     "target": "ES2022",
     "module": "Node16",
     "moduleResolution": "Node16",
+    "types": ["node"],
     "declaration": true,
     "declarationDir": "./lib",
     "strict": true,

diff --git a/typedoc.json b/typedoc.json
index 56b54140228da3407523519ce5bb667d31a6b56d..4ae0d9f6064450430d55de49007b1b274ba2a79b 100644 (file)
--- a/typedoc.json
+++ b/typedoc.json
@@ -5,5 +5,12 @@
   "out": "./docs",
   "readme": "none",
   "projectDocuments": ["./docs/*.md"],
-  "includeVersion": true
+  "includeVersion": true,
+  "treatWarningsAsErrors": true,
+  "excludeInternal": true,
+  "externalSymbolLinkMappings": {
+    "@types/node": {
+      "EventEmitter.defaultMaxListeners": "https://nodejs.org/api/events.html#eventsdefaultmaxlisteners"
+    }
+  }
 }

diff --git a/typedoc.mjs b/typedoc.mjs
index 328fb0c8e7fb6028d705b7ae406e13aaec164ff0..15f501301b8ad1bc681bc6475784f30dd84cec49 100644 (file)
--- a/typedoc.mjs
+++ b/typedoc.mjs
@@ -1,32 +1,28 @@
-import { execSync } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+const root = dirname(fileURLToPath(import.meta.url))
+const tmpDir = join(root, 'tmp')
+const docsDir = join(root, 'docs')
+const markdownFiles = readdirSync(docsDir).filter(file => file.endsWith('.md'))
+
+mkdirSync(tmpDir, { recursive: true })
+for (const markdownFile of markdownFiles) {
+  copyFileSync(join(docsDir, markdownFile), join(tmpDir, markdownFile))
+}
+
 try {
-  mkdirSync(join(dirname(fileURLToPath(import.meta.url)), 'tmp'), {
-    recursive: true,
+  // execFileSync inherits stdio and throws on non-zero exit, propagating the
+  // typedoc exit status to this wrapper's parent (pnpm). Wrapping in
+  // try/finally ensures the docs/*.md restoration runs even on failure.
+  execFileSync('pnpm', ['exec', 'typedoc', ...process.argv.slice(2)], {
+    stdio: 'inherit',
   })
-  const markdownFiles = readdirSync(
-    join(dirname(fileURLToPath(import.meta.url)), 'docs')
-  ).filter(file => file.endsWith('.md'))
+} finally {
   for (const markdownFile of markdownFiles) {
-    copyFileSync(
-      join(dirname(fileURLToPath(import.meta.url)), 'docs', markdownFile),
-      join(dirname(fileURLToPath(import.meta.url)), 'tmp', markdownFile)
-    )
+    copyFileSync(join(tmpDir, markdownFile), join(docsDir, markdownFile))
   }
-  execSync('pnpm exec typedoc', { stdio: 'inherit' })
-  for (const markdownFile of markdownFiles) {
-    copyFileSync(
-      join(dirname(fileURLToPath(import.meta.url)), 'tmp', markdownFile),
-      join(dirname(fileURLToPath(import.meta.url)), 'docs', markdownFile)
-    )
-  }
-  rmSync(join(dirname(fileURLToPath(import.meta.url)), 'tmp'), {
-    force: true,
-    recursive: true,
-  })
-} catch (e) {
-  console.error(e)
+  rmSync(tmpDir, { force: true, recursive: true })
 }