typedoc-plugin-missing-exports - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

CHANGELOG.md

@@ -0,45 +1,51 @@
+### 2.2.0 (2024-01-14)
+
+- Fixed an issue where if a re-exported symbol referenced an internal symbol, and more than one entry point was provided to TypeDoc,
+  this plugin would add the internal symbol to the last module, rather than the one it was associated with, #22.
+- Added `--placeInternalsInOwningModule` option.
+
 ### 2.1.0 (2023-08-25)
 
--   Added support for TypeDoc 0.25.x
+- Added support for TypeDoc 0.25.x
 
 ### 2.0.1 (2023-07-29)
 
--   Fixed memory leak when running in watch mode / packages mode, TypeStrong/typedoc#2339
+- Fixed memory leak when running in watch mode / packages mode, TypeStrong/typedoc#2339
 
 ### 2.0.0 (2023-04-15)
 
--   BREAKING: Drop support for TypeDoc 0.22 and 0.23
+- BREAKING: Drop support for TypeDoc 0.22 and 0.23
 
 ### 1.0.0 (2022-08-12)
 
--   BREAKING: Will now create an `<internals>`**module** rather than a **namespace** to allow support for referenced default exports, #15.
--   BREAKING: Renamed `internalNamespace` option to `internalModule`
+- BREAKING: Will now create an `<internals>` **module** rather than a **namespace** to allow support for referenced default exports, #15.
+- BREAKING: Renamed `internalNamespace` option to `internalModule`
 
 ### 0.23.0 (2022-06-26)
 
--   Add support for TypeDoc 0.23.x
--   Dropped support for Node 12.
+- Add support for TypeDoc 0.23.x
+- Dropped support for Node 12.
 
 ### 0.22.6 (2021-11-24)
 
--   Fix crash if `@types/node` is installed and `Global` is referenced, #5.
+- Fix crash if `@types/node` is installed and `Global` is referenced, #5.
 
 ### 0.22.5 (2021-11-24)
 
--   Fix crash if `@types/node` is installed and `Date` is referenced, #5.
+- Fix crash if `@types/node` is installed and `Date` is referenced, #5.
 
 ### 0.22.4 (2021-11-6)
 
--   Fix crash if a module without types is referenced as a type, #3.
+- Fix crash if a module without types is referenced as a type, #3.
 
 ### 0.22.3 (2021-09-15)
 
--   Fix broken published package again.
+- Fix broken published package again.
 
 ### 0.22.2 (2021-09-15)
 
--   Fix broken published package.
+- Fix broken published package.
 
 ### 0.22.1 (2021-09-15)
 
--   Add repo info for linking to plugin from npm.
+- Add repo info for linking to plugin from npm.

index.js

@@ -1,8 +0,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.load = void 0;
-const assert_1 = require("assert");
-const typedoc_1 = require("typedoc");
+import { Converter, ReflectionKind, TypeScript as ts, ReferenceType, ParameterType, } from "typedoc";
 let hasMonkeyPatched = false;
-function load(app) {
+const ModuleLike = ReflectionKind.Project | ReflectionKind.Module;
+const InternalModule = Symbol();
+export function load(app) {
     if (hasMonkeyPatched) {
@@ -12,10 +10,8 @@ throw new Error("typedoc-plugin-missing-exports cannot be loaded multiple times");
     hasMonkeyPatched = true;
-    let activeReflection;
     const referencedSymbols = new Map();
-    const symbolToActiveRefl = new Map();
+    const symbolToOwningModule = new Map();
     const knownPrograms = new Map();
-    function discoverMissingExports(context, program) {
+    function discoverMissingExports(owningModule, context, program) {
         // An export is missing if if was referenced
         // Is not contained in the documented
-        // And is "owned" by the active reflection
         const referenced = referencedSymbols.get(program) || new Set();
@@ -28,3 +24,3 @@ const ownedByOther = new Set();
             }
-            else if (symbolToActiveRefl.get(s) !== activeReflection) {
+            else if (symbolToOwningModule.get(s) !== owningModule) {
                 referenced.delete(s);
@@ -37,7 +33,7 @@ ownedByOther.add(s);
     // Monkey patch the constructor for references so that we can get every
-    const origCreateSymbolReference = typedoc_1.ReferenceType.createSymbolReference;
-    typedoc_1.ReferenceType.createSymbolReference = function (symbol, context, name) {
-        (0, assert_1.ok)(activeReflection, "active reflection has not been set");
+    const origCreateSymbolReference = ReferenceType.createSymbolReference;
+    ReferenceType.createSymbolReference = function (symbol, context, name) {
+        const owningModule = getOwningModule(context);
         const set = referencedSymbols.get(context.program);
-        symbolToActiveRefl.set(symbol, activeReflection);
+        symbolToOwningModule.set(symbol, owningModule);
         if (set) {
@@ -53,13 +49,24 @@ set.add(symbol);
         name: "internalModule",
-        help: "Define the name of the module that internal symbols which are not exported should be placed into.",
+        help: "[typedoc-plugin-missing-exports] Define the name of the module that internal symbols which are not exported should be placed into.",
         defaultValue: "<internal>",
     });
-    app.converter.on(typedoc_1.Converter.EVENT_CREATE_DECLARATION, (context, refl) => {
-        if (refl.kindOf(typedoc_1.ReflectionKind.Project | typedoc_1.ReflectionKind.Module)) {
+    app.options.addDeclaration({
+        name: "placeInternalsInOwningModule",
+        help: "[typedoc-plugin-missing-exports] If set internal symbols will not be placed into an internals module, but directly into the module which references them.",
+        defaultValue: false,
+        type: ParameterType.Boolean,
+    });
+    app.converter.on(Converter.EVENT_BEGIN, () => {
+        if (app.options.getValue("placeInternalsInOwningModule") &&
+            app.options.isSet("internalModule")) {
+            app.logger.warn(`[typedoc-plugin-missing-exports] Both placeInternalsInOwningModule and internalModule are set, the internalModule option will be ignored.`);
+        }
+    });
+    app.converter.on(Converter.EVENT_CREATE_DECLARATION, (context, refl) => {
+        if (refl.kindOf(ModuleLike)) {
             knownPrograms.set(refl, context.program);
-            activeReflection = refl;
         }
     });
-    app.converter.on(typedoc_1.Converter.EVENT_RESOLVE_BEGIN, function onResolveBegin(context) {
-        const modules = context.project.getChildrenByKind(typedoc_1.ReflectionKind.Module);
+    app.converter.on(Converter.EVENT_RESOLVE_BEGIN, function onResolveBegin(context) {
+        const modules = context.project.getChildrenByKind(ReflectionKind.Module);
         if (modules.length === 0) {
@@ -70,16 +77,22 @@ // Single entry point, just target the project.
         for (const mod of modules) {
-            activeReflection = mod;
             const program = knownPrograms.get(mod);
             if (!program)
                 continue;
-            let missing = discoverMissingExports(context, program);
-            if (!missing || !missing.size)
+            let missing = discoverMissingExports(mod, context, program);
+            if (!missing.size)
                 continue;
             // Nasty hack here that will almost certainly break in future TypeDoc versions.
             context.setActiveProgram(program);
-            const internalNs = context
-                .withScope(mod)
-                .createDeclarationReflection(typedoc_1.ReflectionKind.Module, void 0, void 0, context.converter.application.options.getValue("internalModule"));
-            context.finalizeDeclarationReflection(internalNs);
-            const internalContext = context.withScope(internalNs);
+            let internalContext;
+            if (app.options.getValue("placeInternalsInOwningModule")) {
+                internalContext = context.withScope(mod);
+            }
+            else {
+                const internalNs = context
+                    .withScope(mod)
+                    .createDeclarationReflection(ReflectionKind.Module, void 0, void 0, app.options.getValue("internalModule"));
+                internalNs[InternalModule] = true;
+                context.finalizeDeclarationReflection(internalNs);
+                internalContext = context.withScope(internalNs);
+            }
             // Keep track of which symbols we've tried to convert. If they don't get converted
@@ -96,3 +109,3 @@ // when calling convertSymbol, then the user has excluded them somehow, don't go into
                 }
-                missing = discoverMissingExports(context, program);
+                missing = discoverMissingExports(mod, context, program);
                 for (const s of tried) {
@@ -102,5 +115,6 @@ missing.delete(s);
             } while (missing.size > 0);
-            // All the missing symbols were excluded, so get rid of our namespace.
-            if (!internalNs.children?.length) {
-                context.project.removeReflection(internalNs);
+            // If we added a module and all the missing symbols were excluded, get rid of our namespace.
+            if (internalContext.scope[InternalModule] &&
+                !internalContext.scope.children?.length) {
+                context.project.removeReflection(internalContext.scope);
             }
@@ -111,8 +125,19 @@ context.setActiveProgram(void 0);
         referencedSymbols.clear();
-        symbolToActiveRefl.clear();
+        symbolToOwningModule.clear();
     }, void 0, 1e9);
 }
-exports.load = load;
+function getOwningModule(context) {
+    let refl = context.scope;
+    // Go up the reflection hierarchy until we get to a module
+    while (!refl.kindOf(ModuleLike)) {
+        refl = refl.parent;
+    }
+    // The <internal> module cannot be an owning module.
+    if (refl[InternalModule]) {
+        return refl.parent;
+    }
+    return refl;
+}
 function shouldConvertSymbol(symbol, checker) {
-    while (symbol.flags & typedoc_1.TypeScript.SymbolFlags.Alias) {
+    while (symbol.flags & ts.SymbolFlags.Alias) {
         symbol = checker.getAliasedSymbol(symbol);
@@ -122,3 +147,3 @@ }
     // type declarations. We know nothing about it, so don't convert it.
-    if (symbol.flags & typedoc_1.TypeScript.SymbolFlags.Transient) {
+    if (symbol.flags & ts.SymbolFlags.Transient) {
         return false;
@@ -129,3 +154,3 @@ }
     // inside something that can have properties.
-    if (symbol.flags & typedoc_1.TypeScript.SymbolFlags.Property && symbol.name !== "default") {
+    if (symbol.flags & ts.SymbolFlags.Property && symbol.name !== "default") {
         return false;
@@ -132,0 +157,0 @@ }

package.json

 {
   "name": "typedoc-plugin-missing-exports",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Include non-exported types in TypeDoc documentation",
-  "main": "./index.js",
   "exports": "./index.js",
+  "type": "module",
   "author": "Gerrit Birkeland",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "16",
-    "prettier": "3.0.0",
-    "typedoc": "^0.25.0",
-    "typescript": "^5.2.2",
-    "vitest": "^0.33.0"
+    "@types/node": "18",
+    "outdent": "^0.8.0",
+    "prettier": "3.2.1",
+    "typedoc": "^0.25.7",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
   },
@@ -31,4 +32,5 @@ "repository": {
     "test": "vitest run test/packages.test.ts",
+    "test:doc": "typedoc --plugin ./index.js --tsconfig ./test/packages",
     "build": "tsc"
   }
 }

README.md

@@ -7,7 +7,7 @@ # typedoc-plugin-missing-exports
 
-TypeDoc 0.20 switched from documenting each file individually to documenting based on entry points. TypeDoc looks at each provided entry point and documents all exports from that entry point.
+TypeDoc looks at each entry point provided and documents all exports from that entry point.
 
 For libraries which export their full exposed API, this works well, but some packages are extremely resistant to exporting everything. This plugin is for them. After TypeDoc has finished converting packages, it will look for types which are referenced, but not exported, and place them into an internal module for that entry point (called `<internal>` by default).
 
-If your project references classes which are built into the language (e.g. `HTMLElement`), this package _will_ result in those types being documented to. If you want to prevent this, set TypeDoc's `excludeExternals` option to `true`. The default pattern for determining if a symbol is external will exclude everything within `node_modules`.
+If your project references classes which are built into the language (e.g. `HTMLElement`), this package _will_ result in those types being documented too. If you want to prevent this, set TypeDoc's `excludeExternals` option to `true`. The default pattern for determining if a symbol is external will exclude everything within `node_modules`.
 
@@ -23,6 +23,7 @@ ### Usage
 
--   `internalModule` - Define the name of the module that internal symbols which are not exported should be placed into.
+- `internalModule` - Define the name of the module that internal symbols which are not exported should be placed into.
+- `placeInternalsInOwningModule` - Disable creating a module for internal symbols, and instead place them into the referencing module
 
 ### Additional Reading
 
--   https://github.com/TypeStrong/typedoc/issues/1657
+- https://github.com/TypeStrong/typedoc/issues/1657

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

11389

increased by15.27%

Lines of code

149

increased by20.16%

Number of lines in readme file

28

increased by3.7%

Is type module

Yes

Worsened metrics

Dev dependency count

6

increased by20%

No dependency changes