fix(typedoc0.16): Some fixes for 0.16.x (WIP)

- Use built-in getRawComment for version 0.16+.  Continue to use monkey patch for version < 0.16 (for now, not sure if this is necessary)
- Clean up project.reflections[] when deleting a reflection
- Use registerReflection in 0.16+ to update symbol mappings
- Add isTypedocVersion() helper

Author: christopherthielen

.gitignore

@@ -6,6 +6,7 @@
 # Built using tsc
 plugin.js
 getRawComment.js
+typedocVersion.js
 
 # test cache
 .downstream_cache

downstream_projects.json

@@ -9,7 +9,8 @@
     "typedoc-0.11.1": "./test/typedoc-0.11.1",
     "typedoc-0.12.0": "./test/typedoc-0.12.0",
     "typedoc-0.13.0": "./test/typedoc-0.13.0",
-    "typedoc-0.14.2": "./test/typedoc-0.14.2"
+    "typedoc-0.14.2": "./test/typedoc-0.14.2",
+    "typedoc-0.15.8": "./test/typedoc-0.15.8"
   },
   "nohoist": ["**/typedoc-plugin-external-module-name"]
 }

getRawComment.ts

@@ -9,9 +9,12 @@
 import * as ts from 'typescript';
 import * as _ts from 'typedoc/dist/lib/ts-internal';
 import { getRawComment as realGetRawComment } from 'typedoc/dist/lib/converter/factories/comment';
+import { isTypedocVersion } from './typedocVersion';
+
+const useMonkeyPatchedGetRawComment = isTypedocVersion('< 0.16.0');
 
 function monkeyPatch() {
-  const realGetJSDocCommentRanges = _ts.getJSDocCommentRanges;
+  const realGetJSDocCommentRanges = (_ts as any).getJSDocCommentRanges;
 
   function patchedGetJSDocCommentRanges() {
     const result = realGetJSDocCommentRanges.apply(this, arguments);
@@ -28,8 +31,9 @@ function monkeyPatch() {
     tsinternal.getJSDocCommentRanges = realGetJSDocCommentRanges;
   };
 }
+const getRawComment = useMonkeyPatchedGetRawComment ? monkeyPatchedGetRawComment : realGetRawComment;
 
-function getRawComment(node: ts.Node): string {
+function monkeyPatchedGetRawComment(node: ts.Node): string {
   let unpatch = monkeyPatch();
   try {
     return realGetRawComment(node);

package.json

@@ -20,19 +20,25 @@
   "author": "Chris Thielen",
   "license": "MIT",
   "dependencies": {
+    "lodash": "^4.1.2",
     "semver": "^7.1.1"
   },
   "peerDependencies": {
     "typedoc": ">=0.7.0 <0.15.0"
   },
   "devDependencies": {
     "@types/handlebars": "^4.0.37",
+    "@types/lodash": "^4.1.6",
+    "@types/node": "^13.1.6",
     "@types/semver": "^6.2.0",
     "@uirouter/publish-scripts": "^2.3.24",
     "husky": "^2.2.0",
     "prettier": "^1.13.7",
     "pretty-quick": "^1.4.1",
-    "typedoc": "~0.14.0"
+    "typedoc": "0.16.4"
+  },
+  "resolutions": {
+    "typedoc": "0.16.4"
   },
   "husky": {
     "hooks": {

plugin.ts

@@ -1,3 +1,4 @@
+import * as ts from 'typescript';
 import { Component, ConverterComponent } from 'typedoc/dist/lib/converter/components';
 import { Context } from 'typedoc/dist/lib/converter/context';
 import { Converter } from 'typedoc/dist/lib/converter/converter';
@@ -6,12 +7,9 @@ import { Comment, ProjectReflection } 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 { getRawComment } from './getRawComment';
 
-import { satisfies } from 'semver';
-const version = require('typedoc/package.json').version;
-const useOldDeclarationReflectionConstructor = satisfies(version, '< 0.14.0');
-
 /**
  * This plugin allows an ES6 module to specify its TypeDoc name.
  * It also allows multiple ES6 modules to be merged together into a single TypeDoc module.
@@ -79,7 +77,7 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
         this.moduleRenames.push({
           renameTo: match[1],
           preferred: preferred != null,
-          symbolId: context.getSymbolID(node.symbol),
+          symbol: node.symbol,
           reflection: <ContainerReflection>reflection,
         });
       }
@@ -116,8 +114,7 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
       for (let i = 0; i < nameParts.length - 1; ++i) {
         let child: DeclarationReflection = parent.children.filter(ref => ref.name === nameParts[i])[0];
         if (!child) {
-          if (useOldDeclarationReflectionConstructor) {
-            // for typedoc < 0.15.0
+          if (isTypedocVersion('< 0.14.0')) {
             child = new (DeclarationReflection as any)(parent, nameParts[i], ReflectionKind.ExternalModule);
           } else {
             child = new DeclarationReflection(nameParts[i], ReflectionKind.ExternalModule, parent);
@@ -147,11 +144,11 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
         }
         item.reflection.parent = parent;
         parent.children.push(<DeclarationReflection>renaming);
-        updateSymbolMapping(context.project, item.symbolId, parent.id);
+        updateSymbolMapping(context, item.symbol, parent);
         return;
       }
 
-      updateSymbolMapping(context.project, item.symbolId, mergeTarget.id);
+      updateSymbolMapping(context, item.symbol, mergeTarget);
       if (!mergeTarget.children) {
         mergeTarget.children = [];
       }
@@ -171,7 +168,7 @@ 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;
-      CommentPlugin.removeReflection(context.project, renaming);
+      removeReflection(context, renaming);
 
       // Remove @module and @preferred from the comment, if found.
       CommentPlugin.removeTags(mergeTarget.comment, 'module');
@@ -183,13 +180,25 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
   }
 }
 
+function removeReflection(context: Context, reflection: Reflection) {
+  CommentPlugin.removeReflection(context.project, reflection);
+  if (isTypedocVersion('>=0.16.0 <0.17.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(project: ProjectReflection, symbolId: number, mappedReflectionId: number) {
-  project.symbolMapping[symbolId] = mappedReflectionId;
+function updateSymbolMapping(context: Context, symbol: ts.Symbol, reflection: Reflection) {
+  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);
+  }
 }
 
 function isEmptyComment(comment: Comment) {
@@ -199,6 +208,6 @@ function isEmptyComment(comment: Comment) {
 interface ModuleRename {
   renameTo: string;
   preferred: boolean;
-  symbolId: number;
+  symbol: ts.Symbol;
   reflection: ContainerReflection;
 }

typedocVersion.ts

@@ -0,0 +1,10 @@
+import { memoize } from 'lodash';
+import { satisfies } from 'semver';
+
+const typedocVersion = require('typedoc/package.json').version;
+
+function checkTypedocVersion(semverString: string) {
+  return satisfies(typedocVersion, semverString);
+}
+
+export const isTypedocVersion = memoize(checkTypedocVersion);