Merge branch 'GH-9-source-info-in-replacer-function'

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2024-01-21
+### Added
+-   When using a replacer function one now has access to the source code location through the function context "this". (see README example)
+
 ## [3.2.0] - 2023-09-01
 ### Added
 -   Added support for latest TypeDoc version 0.25.x.
@@ -38,7 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0] - 2022-04-07
 First release
 
-[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-text/compare/v3.2.0...HEAD
+[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-text/compare/v3.3.0...HEAD
+[3.3.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v3.3.0
 [3.2.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v3.2.0
 [3.1.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v3.1.0
 [3.0.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v3.0.0

README.md

@@ -60,7 +60,10 @@ module.exports = {
             {
                 pattern: "King Kong",
                 flags: "gi",
-                replace: (match) => {
+                replace: function (match) {
+                    if (this.sources && this.sources[0].fileName == "king-kong.ts") {
+                        return match + " is home!";
+                    }
                     return match + " is the greatest!";
                 },
             },
@@ -76,7 +79,7 @@ Explanation:
 | **inCodeCommentText** | Specifies if the plugin should replace in the text of comments (not including the text of tags like the description of parameters for a method) in your code. (optional - defaults to `true`) |
 | **inCodeCommentTags** | Specifies if the plugin should replace in the text of tags (like the description of parameters for a method) in your code comments. (optional - defaults to `true`) |
 | **inIncludedFiles**   | Specifies if the plugin should replace in included markdown files (this includes the main README). (optional - defaults to `true`) |
-| **replacements**      | The search patterns and texts they should be replaced with. (`pattern` is the search Regex and `flags` are the optional Regex flags that default to `g`. `replace` can be a string constant or a [replacer function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_function_as_the_replacement) that returns the new text for each match.) |
+| **replacements**      | The search patterns and texts they should be replaced with. (`pattern` is the search Regex and `flags` are the optional Regex flags that default to `g`. `replace` can be a string constant or a [replacer function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_function_as_the_replacement) that returns the new text for each match. The replacer function also has access to source information through the function context `this` - see example above where the `sources` property is an array of [TypeDoc SourceReference](https://typedoc.org/api/classes/Models.SourceReference.html) objects.) |
 
 ## Bugs
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "typedoc-plugin-replace-text",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "description": "Plugin for TypeDoc that replaces text in the documentation",
     "author": {
         "name": "Krisztián Balla",
@@ -13,17 +13,17 @@
     ],
     "devDependencies": {
         "@types/node": "18.16.17",
-        "@typescript-eslint/eslint-plugin": "6.5.0",
-        "@typescript-eslint/parser": "6.5.0",
-        "cypress": "12.17.1",
-        "eslint": "8.48.0",
-        "eslint-plugin-jsdoc": "46.5.1",
+        "@typescript-eslint/eslint-plugin": "6.19.0",
+        "@typescript-eslint/parser": "6.19.0",
+        "cypress": "13.6.3",
+        "eslint": "8.56.0",
+        "eslint-plugin-jsdoc": "48.0.2",
         "eslint-plugin-ordered-imports": "0.6.0",
-        "eslint-plugin-unicorn": "48.0.1",
-        "prettier": "3.0.3",
-        "rimraf": "5.0.1",
-        "typedoc": "0.25.0",
-        "typescript": "5.2.2"
+        "eslint-plugin-unicorn": "50.0.1",
+        "prettier": "3.2.4",
+        "rimraf": "5.0.5",
+        "typedoc": "0.25.7",
+        "typescript": "5.3.3"
     },
     "peerDependencies": {
         "typedoc": "^0.24.8 || 0.25.x"

src/plugin.ts

@@ -1,5 +1,6 @@
-import { Application, CommentDisplayPart, Context, Converter, MarkdownEvent } from "typedoc";
+import { Application, CommentDisplayPart, Context, Converter, MarkdownEvent, SourceReference } from "typedoc";
 import { PluginOptions } from "./plugin_options";
+import { hasSources } from "./utils";
 
 /**
  * The "Replace Text" plugin.
@@ -36,12 +37,11 @@ export class Plugin {
             this.onTypeDocConverterResolveBegin(c),
         );
 
-        // The priority makes sure that our event handler is called before TypeDoc converts the markdown content
         typedoc.renderer.on(
             MarkdownEvent.INCLUDE,
             (e: MarkdownEvent) => this.onTypeDocMarkdownInclude(e),
             typedoc,
-            100,
+            100, // this makes sure that our event handler is called before TypeDoc converts the markdown content
         );
     }
 
@@ -73,11 +73,15 @@ export class Plugin {
             const reflection = project.reflections[key];
 
             if (reflection.comment) {
+                const sources = hasSources(reflection) ? reflection.sources ?? [] : undefined;
+
                 if (this.options.replaceInCodeCommentText) {
-                    this.applyReplacementsToCommentParts(reflection.comment.summary);
+                    this.applyReplacementsToCommentParts(reflection.comment.summary, sources);
                 }
                 if (this.options.replaceInCodeCommentTags) {
-                    reflection.comment.blockTags.forEach((tag) => this.applyReplacementsToCommentParts(tag.content));
+                    reflection.comment.blockTags.forEach((tag) =>
+                        this.applyReplacementsToCommentParts(tag.content, sources),
+                    );
                 }
             }
         }
@@ -113,26 +117,28 @@ export class Plugin {
     /**
      * Applies the replacements to the given text parts.
      * @param parts The text parts on which to apply the replacements.
+     * @param sources Information about the source of the comment parts.
      */
-    private applyReplacementsToCommentParts(parts: CommentDisplayPart[]): void {
+    private applyReplacementsToCommentParts(parts: CommentDisplayPart[], sources?: SourceReference[]): void {
         parts.forEach((part) => {
-            part.text = this.applyReplacementsToString(part.text);
+            part.text = this.applyReplacementsToString(part.text, sources);
         });
     }
 
     /**
      * Applies the replacements to the given string.
      * @param str The string on which to apply the replacements.
+     * @param sources Information about the source of the string.
      * @returns The string with the replacements applied to it.
      */
-    private applyReplacementsToString(str: string): string {
+    private applyReplacementsToString(str: string, sources?: SourceReference[]): string {
         let result = str;
 
         for (const replacement of this.options.replacements) {
             result =
                 typeof replacement.replace === "string"
                     ? result.replace(replacement.regex, replacement.replace)
-                    : result.replace(replacement.regex, replacement.replace); // duplication but otherwise TS complains
+                    : result.replace(replacement.regex, replacement.replace.bind({ sources }));
         }
 
         return result;

src/plugin_options.ts

@@ -1,4 +1,4 @@
-import { Application, ParameterType } from "typedoc";
+import { Application, ParameterType, SourceReference } from "typedoc";
 
 /**
  * Extend typedoc's options with the plugin's option using declaration merging.
@@ -38,7 +38,7 @@ type ReplaceInfoFromConfig = {
     flags?: string;
 
     /** The text that should be used as a replacement or a function that is called separately for each match. */
-    replace: string | Parameters<string["replace"]>[1];
+    replace: string | (Parameters<string["replace"]>[1] & ThisType<{ sources: SourceReference[] | undefined }>);
 };
 
 /**

src/utils.ts

@@ -0,0 +1,16 @@
+import { DeclarationReflection, ReferenceReflection, Reflection, SignatureReflection } from "typedoc";
+
+/**
+ * Checks if the given reflection provides source code information.
+ * @param reflection The reflection to check.
+ * @returns True if the given reflection provides source code information, false otherwise.
+ */
+export function hasSources(
+    reflection: Reflection,
+): reflection is DeclarationReflection | ReferenceReflection | SignatureReflection {
+    return (
+        reflection instanceof DeclarationReflection ||
+        reflection instanceof ReferenceReflection ||
+        reflection instanceof SignatureReflection
+    );
+}

test/replace-only-in-code-comment-tags/tsconfig.json

@@ -1,3 +1,3 @@
 {
-    "include": ["input"]
+    "include": ["input"],
 }

test/replace-only-in-code-comment-text/tsconfig.json

@@ -1,3 +1,3 @@
 {
-    "include": ["input"]
+    "include": ["input"],
 }

test/replace-only-in-included-files/tsconfig.json

@@ -1,3 +1,3 @@
 {
-    "include": ["input"]
+    "include": ["input"],
 }

test/replace-with-function/test.cy.ts

@@ -7,6 +7,7 @@ describe("functions/A.html", () => {
     });
 
     it("has the replaced text in the comment description", () => {
+        // Note: in the typedoc.config.cjs the replacer function also checks for available source code information
         cy.contains(descriptionSelector, "WAS_REPLACED_BY_FUNCTION");
         cy.contains(descriptionSelector, "REPLACE1").should("not.exist");
     });

test/replace-with-function/tsconfig.json

@@ -1,3 +1,3 @@
 {
-    "include": ["input"]
+    "include": ["input"],
 }

test/replace-with-function/typedoc.config.cjs

@@ -13,8 +13,12 @@ module.exports = {
         replacements: [
             {
                 pattern: "REPLACE1",
-                // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- No types in JS, duh...
-                replace: () => {
+                // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+                replace: function () {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                    if (this.sources?.[0].fileName !== "a.ts") {
+                        throw new Error("Expected to see source code information for the file 'a.ts'");
+                    }
                     return "WAS_REPLACED_BY_FUNCTION";
                 },
             },