fix: handle more relative path cases in doc command

ipfs · Jul 26, 2023 · d6f1202 · d6f1202
1 parent 4373c38
commit d6f1202
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 30 deletions.
diff --git a/src/check-project/check-typedoc-files.js b/src/check-project/check-typedoc-files.js
@@ -14,6 +14,11 @@ export async function checkTypedocFiles (projectDir, isTypescriptProject) {
   console.info('Check typedoc files')
 
   const pkg = fs.readJSONSync(path.join(projectDir, 'package.json'))
+
+  if (pkg.exports == null) {
+    return
+  }
+
   const entryPoints = Object.values(pkg.exports)
     .map(e => {
       const path = e.import
@@ -27,7 +32,7 @@ export async function checkTypedocFiles (projectDir, isTypescriptProject) {
       return path
     })
 
-  await ensureFileHasContents(JSON.stringify({
+  await ensureFileHasContents(projectDir, 'typedoc.json', JSON.stringify({
     entryPoints
-  }, null, 2), 'typedoc.json')
+  }, null, 2))
 }
diff --git a/src/docs/type-indexer-plugin.js b/src/docs/type-indexer-plugin.js
@@ -1,3 +1,5 @@
+/* eslint-disable max-depth */
+
 import fs from 'fs'
 import path from 'path'
 import { RendererEvent, ReflectionKind } from 'typedoc'
@@ -23,6 +25,7 @@ const MODELS = [
  * @property {string} [Documentation.outputDir]
  *
  * @typedef {import('../utils.js').Project} Project
+ * @typedef {import('typedoc/dist/lib/models/reflections').DeclarationReflection} DeclarationReflection
  */
 
 /**
@@ -92,22 +95,35 @@ export function load (Application) {
 
       // workaround for https://github.com/TypeStrong/typedoc/issues/2338
       if (!path.isAbsolute(source.fullFileName)) {
-        const project = urlMapping.model.parent
-        const projectDir = projects[project.name]?.dir
+        // did we get lucky?
+        const p = path.join(process.cwd(), source.fullFileName)
 
-        if (!projectDir) {
-          Application.logger.warn(`Full file name "${source.fullFileName}" was not absolute but could not find containing project - see https://github.com/TypeStrong/typedoc/issues/2338`)
-          continue
+        if (fs.existsSync(p)) {
+          source.fullFileName = p
         } else {
-          const fullFileName = `${projectDir}/src/${source.fullFileName}`
+          const project = findParentProject(urlMapping.model)
 
-          if (fs.existsSync(fullFileName)) {
-            Application.logger.info(`Full file name of source was not absolute, overriding ${source.fullFileName} -> ${fullFileName} - see https://github.com/TypeStrong/typedoc/issues/2338`)
+          if (project == null) {
+            Application.logger.warn(`Full file name "${source.fullFileName}" was not absolute but could not detect containing module definition - see https://github.com/TypeStrong/typedoc/issues/2338`)
+            continue
+          }
 
-            source.fullFileName = fullFileName
-          } else {
-            Application.logger.warn(`Full file name "${source.fullFileName}" was not absolute, found containing project but could not locate source file in project - see https://github.com/TypeStrong/typedoc/issues/2338`)
+          const projectDir = projects[project.name]?.dir
+
+          if (projectDir == null) {
+            Application.logger.warn(`Full file name "${source.fullFileName}" was not absolute but could not find containing project "${project.name}" - see https://github.com/TypeStrong/typedoc/issues/2338`)
             continue
+          } else {
+            const fullFileName = `${projectDir}/src/${source.fullFileName}`
+
+            if (fs.existsSync(fullFileName)) {
+              Application.logger.info(`Full file name of source was not absolute, overriding ${source.fullFileName} -> ${fullFileName} - see https://github.com/TypeStrong/typedoc/issues/2338`)
+
+              source.fullFileName = fullFileName
+            } else {
+              Application.logger.warn(`Full file name "${source.fullFileName}" was not absolute, found containing project but could not locate source file in project - see https://github.com/TypeStrong/typedoc/issues/2338`)
+              continue
+            }
           }
         }
       }
@@ -250,3 +266,24 @@ function makeAbsolute (p) {
 
   return p
 }
+
+/**
+ * @param {any} model
+ * @param {Set<any>} seen
+ * @returns {DeclarationReflection | undefined}
+ */
+function findParentProject (model, seen = new Set()) {
+  const parent = model.parent
+
+  if (seen.has(parent)) {
+    return
+  } else {
+    seen.add(parent)
+  }
+
+  if (parent.kind === ReflectionKind.Module) {
+    return parent
+  }
+
+  return findParentProject(parent, seen)
+}
diff --git a/src/docs/unknown-symbol-resolver-plugin.js b/src/docs/unknown-symbol-resolver-plugin.js
@@ -7,8 +7,12 @@ const knownSymbols = {
     'Chai.ChaiStatic': 'https://www.chaijs.com/api/',
     'Chai.Assertion': 'https://www.chaijs.com/api/assert/'
   },
+  '@types/mocha': {
+    'NodeJS.EventEmitter': 'https://nodejs.org/dist/latest-v19.x/docs/api/events.html#class-eventemitter'
+  },
   '@types/node': {
     EventEmitter: 'https://nodejs.org/dist/latest-v19.x/docs/api/events.html#class-eventemitter',
+    'NodeJS.EventEmitter': 'https://nodejs.org/dist/latest-v19.x/docs/api/events.html#class-eventemitter',
     Server: 'https://nodejs.org/dist/latest-v19.x/docs/api/net.html#class-netserver',
     IncomingMessage: 'https://nodejs.org/dist/latest-v19.x/docs/api/http.html#class-httpincomingmessage',
     ServerResponse: 'https://nodejs.org/dist/latest-v19.x/docs/api/http.html#class-httpserverresponse',

diff --git a/src/utils.js b/src/utils.js
@@ -519,31 +519,35 @@ function * _glob (base, dir, pattern, options) {
 
   const d = fs.opendirSync(p)
 
-  while (true) {
-    const entry = d.readSync()
+  try {
+    while (true) {
+      const entry = d.readSync()
 
-    if (entry == null) {
-      break
-    }
+      if (entry == null) {
+        break
+      }
 
-    const relativeEntryPath = path.join(dir, entry.name)
-    const absoluteEntryPath = path.join(base, dir, entry.name)
+      const relativeEntryPath = path.join(dir, entry.name)
+      const absoluteEntryPath = path.join(base, dir, entry.name)
 
-    let match = minimatch(relativeEntryPath, pattern, options)
+      let match = minimatch(relativeEntryPath, pattern, options)
 
-    const isDirectory = entry.isDirectory()
+      const isDirectory = entry.isDirectory()
 
-    if (isDirectory && options.nodir === true) {
-      match = false
-    }
+      if (isDirectory && options.nodir === true) {
+        match = false
+      }
 
-    if (match) {
-      yield options.absolute === true ? absoluteEntryPath : relativeEntryPath
-    }
+      if (match) {
+        yield options.absolute === true ? absoluteEntryPath : relativeEntryPath
+      }
 
-    if (isDirectory) {
-      yield * _glob(base, relativeEntryPath, pattern, options)
+      if (isDirectory) {
+        yield * _glob(base, relativeEntryPath, pattern, options)
+      }
     }
+  } finally {
+    d.closeSync()
   }
 }