From a4c2af2b3e97993b51cdbbdf0522fcfda111c873 Mon Sep 17 00:00:00 2001
From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= <jerome.benoit@piment-noir.org>
Date: Sat, 16 May 2026 01:41:40 +0200
Subject: [PATCH] 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.
---
 tsconfig.json |  1 +
 typedoc.json  |  9 ++++++++-
 typedoc.mjs   | 42 +++++++++++++++++++-----------------------
 3 files changed, 28 insertions(+), 24 deletions(-)

diff --git a/tsconfig.json b/tsconfig.json
index b07e79437..6564c98b0 100644
--- 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 56b541402..4ae0d9f60 100644
--- 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 328fb0c8e..15f501301 100644
--- 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 })
 }
-- 
2.43.0