fix: Re-add compatibility for typedoc < 0.17.0

christopherthielen · Apr 27, 2020 · c255f1e · c255f1e
1 parent a2c5b7a
commit c255f1e
Show file tree

Hide file tree

Showing 5 changed files with 93 additions and 67 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        typedoc_version: [0.5.10, 0.6.0, 0.7.2, 0.8.0, 0.9.0, 0.10.0, 0.11.1, 0.12.0, 0.13.0, 0.14.2, 0.15.8, 0.16.5]
+        typedoc_version: [0.7.2, 0.8.0, 0.9.0, 0.10.0, 0.11.1, 0.12.0, 0.13.0, 0.14.2, 0.15.8, 0.16.5, 0.17.6]
     steps:
       - uses: actions/checkout@v2
       - name: Prepare to Test Downstream Projects

diff --git a/package.json b/package.json
@@ -37,9 +37,6 @@
     "pretty-quick": "^2.0.1",
     "typedoc": "0.17.6"
   },
-  "resolutions": {
-    "typedoc": "0.16.4"
-  },
   "husky": {
     "hooks": {
       "pre-commit": "pretty-quick --staged"

diff --git a/typedoc-plugin-external-module-name.ts b/typedoc-plugin-external-module-name.ts
@@ -6,7 +6,7 @@ import { Comment } from 'typedoc/dist/lib/models';
 import { Reflection, ReflectionKind } from 'typedoc/dist/lib/models/reflections/abstract';
 import { ContainerReflection } from 'typedoc/dist/lib/models/reflections/container';
 import { DeclarationReflection } from 'typedoc/dist/lib/models/reflections/declaration';
-import { isTypedocVersion } from './typedocVersion';
+import { createChildReflection, removeReflection, removeTags, updateSymbolMapping } from './typedocVersion';
 import { getRawComment } from './getRawComment';
 
 /**
@@ -83,8 +83,8 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
     }
 
     if (reflection.comment) {
-      reflection.comment.removeTags('module');
-      reflection.comment.removeTags('preferred');
+      removeTags(reflection.comment, 'module');
+      removeTags(reflection.comment, 'preferred');
       if (isEmptyComment(reflection.comment)) {
         delete reflection.comment;
       }
@@ -104,20 +104,16 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
     }, []);
 
     // Process each rename
-    this.moduleRenames.forEach(item => {
+    this.moduleRenames.forEach((item) => {
       let renaming = <ContainerReflection>item.reflection;
 
       // Find or create the module tree until the child's parent (each level is separated by .)
       let nameParts = item.renameTo.split('.');
       let parent: ContainerReflection = context.project;
       for (let i = 0; i < nameParts.length - 1; ++i) {
-        let child: DeclarationReflection = parent.children.filter(ref => ref.name === nameParts[i])[0];
+        let child: DeclarationReflection = parent.children.filter((ref) => ref.name === nameParts[i])[0];
         if (!child) {
-          if (isTypedocVersion('< 0.14.0')) {
-            child = new (DeclarationReflection as any)(parent, nameParts[i], ReflectionKind.Module);
-          } else {
-            child = new DeclarationReflection(nameParts[i], ReflectionKind.Module, parent);
-          }
+          child = createChildReflection(parent, nameParts[i]);
           child.parent = parent;
           child.children = [];
           context.project.reflections[child.id] = child;
@@ -128,7 +124,7 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
 
       // Find an existing module with the child's name in the last parent. Use it as the merge target.
       let mergeTarget = <ContainerReflection>(
-        parent.children.filter(ref => ref.kind === renaming.kind && ref.name === nameParts[nameParts.length - 1])[0]
+        parent.children.filter((ref) => ref.kind === renaming.kind && ref.name === nameParts[nameParts.length - 1])[0]
       );
 
       // If there wasn't a merge target, change the name of the current module, connect it to the right parent and exit.
@@ -153,7 +149,7 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
       }
 
       // Since there is a merge target, relocate all the renaming module's children to the mergeTarget.
-      let childrenOfRenamed = refsArray.filter(ref => ref.parent === renaming);
+      let childrenOfRenamed = refsArray.filter((ref) => ref.parent === renaming);
       childrenOfRenamed.forEach((ref: Reflection) => {
         // update links in both directions
         ref.parent = mergeTarget;
@@ -167,12 +163,12 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
       // Now that all the children have been relocated to the mergeTarget, delete the empty module
       // Make sure the module being renamed doesn't have children, or they will be deleted
       if (renaming.children) renaming.children.length = 0;
-      removeReflection(context, renaming);
+      removeReflection(context.project, renaming);
 
       // Remove @module and @preferred from the comment, if found.
       if (mergeTarget.comment) {
-        mergeTarget.comment.removeTags('module');
-        mergeTarget.comment.removeTags('preferred');
+        removeTags(mergeTarget.comment, 'module');
+        removeTags(mergeTarget.comment, 'preferred');
       }
       if (isEmptyComment(mergeTarget.comment)) {
         delete mergeTarget.comment;
@@ -181,33 +177,6 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
   }
 }
 
-function removeReflection(context: Context, reflection: Reflection) {
-  context.project.removeReflection(reflection, true);
-  if (isTypedocVersion('>=0.16.0')) {
-    delete context.project.reflections[reflection.id];
-  }
-}
-
-/**
- * When we delete reflections, update the symbol mapping in order to fix:
- * https://github.com/christopherthielen/typedoc-plugin-external-module-name/issues/313
- * https://github.com/christopherthielen/typedoc-plugin-external-module-name/issues/193
- */
-function updateSymbolMapping(context: Context, symbol: ts.Symbol, reflection: Reflection) {
-  if (!symbol) {
-    return;
-  }
-
-  if (isTypedocVersion('< 0.16.0')) {
-    // (context as any).registerReflection(reflection, null, symbol);
-    (context.project as any).symbolMapping[(symbol as any).id] = reflection.id;
-  } else {
-    // context.registerReflection(reflection, symbol);
-    const fqn = context.checker.getFullyQualifiedName(symbol);
-    (context.project as any).fqnToReflectionIdMap.set(fqn, reflection.id);
-  }
-}
-
 function isEmptyComment(comment: Comment) {
   return !comment || (!comment.text && !comment.shortText && (!comment.tags || comment.tags.length === 0));
 }

diff --git a/typedocVersion.ts b/typedocVersion.ts
@@ -1,5 +1,12 @@
+import * as ts from 'typescript';
+import { Context } from 'typedoc/dist/lib/converter/context';
+import { CommentPlugin } from 'typedoc/dist/lib/converter/plugins';
+import { Comment, ProjectReflection } from 'typedoc/dist/lib/models';
 import { memoize } from 'lodash';
 import { satisfies } from 'semver';
+import { Reflection } from 'typedoc/dist/lib/models/reflections';
+import { ReflectionKind } from 'typedoc/dist/lib/models/reflections/abstract';
+import { DeclarationReflection } from 'typedoc/dist/lib/models/reflections/declaration';
 
 const typedocVersion = require('typedoc/package.json').version;
 
@@ -8,3 +15,51 @@ function checkTypedocVersion(semverString: string) {
 }
 
 export const isTypedocVersion = memoize(checkTypedocVersion);
+
+export function removeTags(comment: Comment, tag: string) {
+  if (isTypedocVersion('< 0.17.0')) {
+    return CommentPlugin.removeTags(comment, tag);
+  } else {
+    comment.removeTags(tag);
+  }
+}
+
+export function removeReflection(project: ProjectReflection, reflection: Reflection) {
+  if (isTypedocVersion('< 0.17.0')) {
+    CommentPlugin.removeReflection(project, reflection);
+  } else {
+    project.removeReflection(reflection, true);
+  }
+
+  if (isTypedocVersion('>=0.16.0')) {
+    delete project.reflections[reflection.id];
+  }
+}
+
+export function createChildReflection(parent: Reflection, name: string) {
+  if (isTypedocVersion('< 0.14.0')) {
+    return new (DeclarationReflection as any)(parent, name, ReflectionKind.Module);
+  } else {
+    return new DeclarationReflection(name, ReflectionKind.Module, parent);
+  }
+}
+
+/**
+ * When we delete reflections, update the symbol mapping in order to fix:
+ * https://github.com/christopherthielen/typedoc-plugin-external-module-name/issues/313
+ * https://github.com/christopherthielen/typedoc-plugin-external-module-name/issues/193
+ */
+export function updateSymbolMapping(context: Context, symbol: ts.Symbol, reflection: Reflection) {
+  if (!symbol) {
+    return;
+  }
+
+  if (isTypedocVersion('< 0.16.0')) {
+    // (context as any).registerReflection(reflection, null, symbol);
+    (context.project as any).symbolMapping[(symbol as any).id] = reflection.id;
+  } else {
+    // context.registerReflection(reflection, symbol);
+    const fqn = context.checker.getFullyQualifiedName(symbol);
+    (context.project as any).fqnToReflectionIdMap.set(fqn, reflection.id);
+  }
+}
diff --git a/yarn.lock b/yarn.lock
@@ -1978,10 +1978,10 @@ typedoc-default-themes@^0.10.1:
   dependencies:
     lunr "^2.3.8"
 
-typedoc-default-themes@^0.7.1:
-  version "0.7.1"
-  resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.7.1.tgz#1b92999162dc816b52b8094f503f254c87f07c28"
-  integrity sha512-s3jeUHc4EY8snIta6lNkUu9+36WMDUnkKm0UQ59w5iPo/4Y2d4+M9CDIKoenYKT5hkg/UnTc3oX48VZZytv8Xw==
+typedoc-default-themes@^0.7.2:
+  version "0.7.2"
+  resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.7.2.tgz#1e9896f920b58e6da0bba9d7e643738d02405a5a"
+  integrity sha512-fiFKlFO6VTqjcno8w6WpTsbCgXmfPHVjnLfYkmByZE7moaz+E2DSpAT+oHtDHv7E0BM5kAhPrHJELP2J2Y2T9A==
   dependencies:
     backbone "^1.4.0"
     jquery "^3.4.1"
@@ -2006,23 +2006,6 @@ typedoc-plugin-ui-router@2.0.1:
   resolved "https://registry.yarnpkg.com/typedoc-plugin-ui-router/-/typedoc-plugin-ui-router-2.0.1.tgz#4c84aa88696454ecb022cf4ff035a08f069fe3e8"
   integrity sha512-bPLFrsvMUL5a7ZR8b1+Wvu+hEGB7dcBXhlBLgPy2JeiL97YwDDtEYYBEzo9IMAYoD/uscq4FLfWonxrOU63L6g==
 
-typedoc@0.16.4, typedoc@^0.16.11:
-  version "0.16.4"
-  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.16.4.tgz#afbf97b421423ec85400886f626c94b18d514cf1"
-  integrity sha512-7pUHKipYmvmnKQtczPp1gFa/19z2lxkWzJVboMKeNRjz4cf82EfGdtcRD146KV0Nl4cAehhU28qcU+dcWn+e4g==
-  dependencies:
-    "@types/minimatch" "3.0.3"
-    fs-extra "^8.1.0"
-    handlebars "^4.7.2"
-    highlight.js "^9.17.1"
-    lodash "^4.17.15"
-    marked "^0.8.0"
-    minimatch "^3.0.0"
-    progress "^2.0.3"
-    shelljs "^0.8.3"
-    typedoc-default-themes "^0.7.1"
-    typescript "3.7.x"
-
 typedoc@0.17.6:
   version "0.17.6"
   resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.17.6.tgz#cab87a72c10e05429016d659a4c3071a5a3ffb61"
@@ -2039,11 +2022,33 @@ typedoc@0.17.6:
     shelljs "^0.8.4"
     typedoc-default-themes "^0.10.1"
 
+typedoc@^0.16.11:
+  version "0.16.11"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.16.11.tgz#95f862c6eba78533edc9af7096d2295b718eddc1"
+  integrity sha512-YEa5i0/n0yYmLJISJ5+po6seYfJQJ5lQYcHCPF9ffTF92DB/TAZO/QrazX5skPHNPtmlIht5FdTXCM2kC7jQFQ==
+  dependencies:
+    "@types/minimatch" "3.0.3"
+    fs-extra "^8.1.0"
+    handlebars "^4.7.2"
+    highlight.js "^9.17.1"
+    lodash "^4.17.15"
+    marked "^0.8.0"
+    minimatch "^3.0.0"
+    progress "^2.0.3"
+    shelljs "^0.8.3"
+    typedoc-default-themes "^0.7.2"
+    typescript "3.7.x"
+
 typescript@3.7.x:
   version "3.7.4"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.7.4.tgz#1743a5ec5fef6a1fa9f3e4708e33c81c73876c19"
   integrity sha512-A25xv5XCtarLwXpcDNZzCGvW2D1S3/bACratYBx2sax8PefsFhlYmkQicKHvpYflFS8if4zne5zT5kpJ7pzuvw==
 
+typescript@>=3.8.3:
+  version "3.8.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.8.3.tgz#409eb8544ea0335711205869ec458ab109ee1061"
+  integrity sha512-MYlEfn5VrLNsgudQTVJeNaQFUAI7DkhnOjdpAp4T+ku1TfQClewlbSuTVHiA+8skNBgaf02TL/kLOvig4y3G8w==
+
 uglify-js@^3.1.4:
   version "3.7.5"
   resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.7.5.tgz#278c7c24927ac5a32d3336fc68fd4ae1177a486a"