Add unit tests for include/includeCode with regions

Author: Gerrit0

CHANGELOG.md

@@ -15,6 +15,10 @@ title: Changelog
 -   Fixed an issue where TypeDoc would incorrectly ignore type arguments in references, #2823.
 -   Improved narrator support for labeling icons, #2832.
 
+### Thanks!
+
+-   @shawninder
+
 ## v0.27.6 (2024-12-26)
 
 ### Features

site/options/comments.md

@@ -185,9 +185,7 @@ Also see [`blockTags`](#blocktags) and [`inlineTags`](#inlinetags).
 ```
 
 Specifies modifier tags which should be copied to all children of the parent reflection.
-
-> [!note]
-> `@deprecated` is a block tag, not a modifier tag, so should not be specified here.
+Note that `@deprecated` is a block tag, not a modifier tag, so should not be specified here.
 
 ## excludeTags
 

src/lib/converter/plugins/IncludePlugin.ts

@@ -90,6 +90,7 @@ export class IncludePlugin extends ConverterComponent {
                                   part.text,
                                   text,
                                   target,
+                                  part.tag,
                               )
                             : requestedLines
                               ? this.getLines(
@@ -98,6 +99,7 @@ export class IncludePlugin extends ConverterComponent {
                                     part.text,
                                     text,
                                     requestedLines,
+                                    part.tag,
                                 )
                               : text,
                         file,
@@ -126,6 +128,7 @@ export class IncludePlugin extends ConverterComponent {
                                       part.text,
                                       text,
                                       target,
+                                      part.tag,
                                   )
                                 : requestedLines
                                   ? this.getLines(
@@ -134,13 +137,14 @@ export class IncludePlugin extends ConverterComponent {
                                         part.text,
                                         text,
                                         requestedLines,
+                                        part.tag,
                                     )
                                   : text,
                         ),
                     };
                 }
             } else {
-                this.logger.warn(
+                this.logger.error(
                     this.logger.i18n.include_0_in_1_specified_2_resolved_to_3_does_not_exist(
                         part.tag,
                         refl.getFriendlyFullName(),
@@ -159,8 +163,20 @@ export class IncludePlugin extends ConverterComponent {
         textPart: string,
         text: string,
         target: string,
+        tag: string,
     ) {
         const regionTagsList = regionTagREsByExt[ext];
+        if (!regionTagsList) {
+            this.logger.error(
+                this.logger.i18n.include_0_tag_in_1_region_2_region_not_supported(
+                    tag,
+                    refl.getFriendlyFullName(),
+                    textPart,
+                ),
+            );
+            return "";
+        }
+
         let found: string | false = false;
         for (const [startTag, endTag] of regionTagsList) {
             const safeTarget = escapeRegExp(target);
@@ -171,7 +187,8 @@ export class IncludePlugin extends ConverterComponent {
             const foundEnd = end && end.length > 0;
             if (foundStart && !foundEnd) {
                 this.logger.error(
-                    this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_close_not_found(
+                    this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_close_not_found(
+                        tag,
                         refl.getFriendlyFullName(),
                         textPart,
                         file,
@@ -182,7 +199,8 @@ export class IncludePlugin extends ConverterComponent {
             }
             if (!foundStart && foundEnd) {
                 this.logger.error(
-                    this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_open_not_found(
+                    this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_open_not_found(
+                        tag,
                         refl.getFriendlyFullName(),
                         textPart,
                         file,
@@ -194,7 +212,8 @@ export class IncludePlugin extends ConverterComponent {
             if (foundStart && foundEnd) {
                 if (start.length > 1) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_open_found_multiple_times(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_open_found_multiple_times(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -205,7 +224,8 @@ export class IncludePlugin extends ConverterComponent {
                 }
                 if (end.length > 1) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_close_found_multiple_times(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_close_found_multiple_times(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -216,7 +236,8 @@ export class IncludePlugin extends ConverterComponent {
                 }
                 if (found) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_found_multiple_times(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_found_multiple_times(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -231,9 +252,10 @@ export class IncludePlugin extends ConverterComponent {
                 );
             }
         }
-        if (!found) {
+        if (found === false) {
             this.logger.error(
-                this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_not_found(
+                this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_not_found(
+                    tag,
                     refl.getFriendlyFullName(),
                     textPart,
                     file,
@@ -244,7 +266,8 @@ export class IncludePlugin extends ConverterComponent {
         }
         if (found.trim() === "") {
             this.logger.warn(
-                this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_region_3_region_empty(
+                this.logger.i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_empty(
+                    tag,
                     refl.getFriendlyFullName(),
                     textPart,
                     file,
@@ -261,6 +284,7 @@ export class IncludePlugin extends ConverterComponent {
         textPart: string,
         text: string,
         requestedLines: string,
+        tag: string,
     ) {
         let output = "";
         const lines = text.split(/\r\n|\r|\n/);
@@ -269,7 +293,8 @@ export class IncludePlugin extends ConverterComponent {
                 const [start, end] = requestedLineString.split("-").map(Number);
                 if (start > end) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_lines_3_invalid_range(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_lines_4_invalid_range(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -280,7 +305,8 @@ export class IncludePlugin extends ConverterComponent {
                 }
                 if (start > lines.length || end > lines.length) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_lines_3_but_only_4_lines(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_lines_4_but_only_5_lines(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -295,7 +321,8 @@ export class IncludePlugin extends ConverterComponent {
                 const requestedLine = Number(requestedLineString);
                 if (requestedLine > lines.length) {
                     this.logger.error(
-                        this.logger.i18n.includeCode_tag_in_0_specified_1_file_2_lines_3_but_only_4_lines(
+                        this.logger.i18n.include_0_tag_in_1_specified_2_file_3_lines_4_but_only_5_lines(
+                            tag,
                             refl.getFriendlyFullName(),
                             textPart,
                             file,
@@ -312,6 +339,7 @@ export class IncludePlugin extends ConverterComponent {
         return output;
     }
 }
+
 function makeCodeBlock(lang: string, code: string) {
     const escaped = code.replace(/`(?=`)/g, "`\u200B");
     return "\n\n```" + lang + "\n" + escaped.trimEnd() + "\n```";
@@ -397,14 +425,22 @@ const regionTagREsByExt: Record<string, RegionTagRETuple[]> = {
         ],
     ],
 };
-regionTagREsByExt["fs"] = regionTagREsByExt["ts"].concat([
-    (regionName) => new RegExp(`(#_region)  *${regionName} *\n`, "g"),
-    (regionName) => new RegExp(`(#_endregion)  *${regionName} *\n`, "g"),
-]);
-regionTagREsByExt["java"] = regionTagREsByExt["ts"].concat([
-    (regionName) => new RegExp(`// *<editor-fold>  *${regionName} *\n`, "g"),
-    (regionName) => new RegExp(`// *</editor-fold>  *${regionName} *\n`, "g"),
-]);
+regionTagREsByExt["fs"] = [
+    ...regionTagREsByExt["ts"],
+    [
+        (regionName) => new RegExp(`(#_region)  *${regionName} *\n`, "g"),
+        (regionName) => new RegExp(`(#_endregion)  *${regionName} *\n`, "g"),
+    ],
+];
+regionTagREsByExt["java"] = [
+    ...regionTagREsByExt["ts"],
+    [
+        (regionName) =>
+            new RegExp(`// *<editor-fold>  *${regionName} *\n`, "g"),
+        (regionName) =>
+            new RegExp(`// *</editor-fold>  *${regionName} *\n`, "g"),
+    ],
+];
 regionTagREsByExt["cpp"] = regionTagREsByExt["c"];
 regionTagREsByExt["less"] = regionTagREsByExt["css"];
 regionTagREsByExt["scss"] = regionTagREsByExt["css"];

src/lib/internationalization/locales/en.cts

@@ -119,15 +119,16 @@ export = {
 
     include_0_in_1_specified_2_resolved_to_3_does_not_exist: `{0} tag in comment for {1} specified "{2}" to include, which was resolved to "{3}" and does not exist or is not a file.`,
     include_0_in_1_specified_2_circular_include_3: `{0} tag in comment for {1} specified "{2}" to include, which resulted in a circular include:\n\t{3}`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_not_found: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled "{3}", but the region was not found in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_close_not_found: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled "{3}", but the region closing comment was not found in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_open_not_found: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled "{3}", but the region opening comment was not found in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_close_found_multiple_times: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled {3}, but the region closing comment was found multiple times in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_open_found_multiple_times: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled {3}, but the region opening comment was found multiple times in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_found_multiple_times: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled {3}, but the region was found multiple times in the file.`,
-    includeCode_tag_in_0_specified_1_file_2_region_3_region_empty: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the region labeled {3}. The region was found but it is empty or contains only whitespace.`,
-    includeCode_tag_in_0_specified_1_file_2_lines_3_invalid_range: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the lines {3}, but an invalid range was specified.`,
-    includeCode_tag_in_0_specified_1_file_2_lines_3_but_only_4_lines: `@includeCode tag in {0} specified "{1}" to include from file "{2}" the lines {3}, but the file only has {4} lines.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_not_found: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled "{4}", but the region was not found in the file.`,
+    include_0_tag_in_1_region_2_region_not_supported: `{0} tag in {1} specified "{2}", but regions are not supported for this file extension.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_close_not_found: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled "{4}", but the region closing comment was not found in the file.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_open_not_found: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled "{4}", but the region opening comment was not found in the file.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_close_found_multiple_times: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled {4}, but the region closing comment was found multiple times in the file.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_open_found_multiple_times: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled {4}, but the region opening comment was found multiple times in the file.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_found_multiple_times: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled {4}, but the region was found multiple times in the file.`,
+    include_0_tag_in_1_specified_2_file_3_region_4_region_empty: `{0} tag in {1} specified "{2}" to include from file "{3}" the region labeled {4}. The region was found but it is empty or contains only whitespace.`,
+    include_0_tag_in_1_specified_2_file_3_lines_4_invalid_range: `{0} tag in {1} specified "{2}" to include from file "{3}" the lines {4}, but an invalid range was specified.`,
+    include_0_tag_in_1_specified_2_file_3_lines_4_but_only_5_lines: `{0} tag in {1} specified "{2}" to include from file "{3}" the lines {4}, but the file only has {5} lines.`,
 
     // output plugins
     custom_css_file_0_does_not_exist: `Custom CSS file at {0} does not exist`,

src/lib/internationalization/translatable.ts

@@ -47,6 +47,7 @@ type TranslationConstraint = [
     BuildConstraint<0 | 1>,
     BuildConstraint<0 | 1 | 2>,
     BuildConstraint<0 | 1 | 2 | 3>,
+    BuildConstraint<0 | 1 | 2 | 3 | 4>,
 ];
 
 // Compiler errors here which says a property is missing indicates that the value on translatable

src/test/behavior.c2.test.ts

@@ -1306,4 +1306,114 @@ describe("Behavior Tests", () => {
             'warn: The signature fn3 has an @param with name "options.c", which was not used',
         );
     });
+
+    it("@includeCode handles regions", () => {
+        const project = convert("includeTag/includeTag");
+        const code = getComment(project, "region");
+        equal(code, "\n\n```ts\nexport const a = 123;\n```");
+    });
+
+    it("@includeCode handles line numbers", () => {
+        const project = convert("includeTag/includeTag");
+        const code = getComment(project, "line");
+        equal(code, "\n\n```ts\nexport const a = 123;\n```");
+    });
+
+    it("@include handles line numbers", () => {
+        const project = convert("includeTag/includeTag");
+        const code = getComment(project, "lineText");
+        equal(code, "Line 3");
+    });
+
+    it("@include handles full files", () => {
+        const project = convert("includeTag/includeTag");
+        const code = getComment(project, "fullFile");
+        equal(code, "Unknown extension doesn't support regions");
+    });
+
+    it("@include works within documents", () => {
+        const project = convert("includeTag/includeTag");
+        const doc = project.getChildByName(["includeInDoc"]);
+        ok(doc?.isDocument());
+        equal(
+            Comment.combineDisplayParts(doc.content),
+            "\n\n```md\n{@includeCode includeInDoc.md}\n```",
+        );
+    });
+
+    it("@includeCode warns about missing regions", () => {
+        convert("includeTag/missingRegion");
+
+        logger.expectMessage(
+            "error: @includeCode *noRegion* the region was not found in the file.",
+        );
+
+        logger.expectMessage(
+            "error: @includeCode *missingStart* the region opening comment was not found in the file.",
+        );
+
+        logger.expectMessage(
+            "error: @includeCode *missingEnd* the region closing comment was not found in the file.",
+        );
+    });
+
+    it("@includeCode warns about duplicate regions", () => {
+        convert("includeTag/duplicateRegion");
+
+        logger.expectMessage(
+            "error: @includeCode *dupStart* the region opening comment was found multiple times in the file.",
+        );
+
+        logger.expectMessage(
+            "error: @includeCode *dupEnd* the region closing comment was found multiple times in the file.",
+        );
+
+        logger.expectMessage(
+            "error: @includeCode *#dup* the region was found multiple times in the file.",
+        );
+    });
+
+    it("@includeCode warns about invalid line ranges", () => {
+        convert("includeTag/invalidLineRanges");
+
+        logger.expectMessage(
+            'error: @includeCode *:100-200" * the file only has*',
+        );
+
+        logger.expectMessage(
+            'error: @includeCode *:200-100" * an invalid range was specified.',
+        );
+
+        logger.expectMessage('error: @includeCode *:300" * the file only has*');
+    });
+
+    it("@includeCode warns about empty region", () => {
+        convert("includeTag/emptyRegion");
+
+        logger.expectMessage("warn: @includeCode *found but it is empty*");
+    });
+
+    it("@includeCode warns about unsupported region", () => {
+        convert("includeTag/unsupportedExtension");
+
+        logger.expectMessage(
+            "error: @includeCode * regions are not supported for this file extension.",
+        );
+    });
+
+    it("@includeCode warns about invalid file references", () => {
+        convert("includeTag/invalidInclude");
+
+        logger.expectMessage(
+            "error: @includeCode *doesNotExist.txt* does not exist or is not a file.",
+        );
+    });
+
+    it("@include warns about circular references", () => {
+        convert("includeTag/circularInclude");
+
+        logger.expectMessage(
+            "error: @include *#circular* resulted in a circular include:*",
+        );
+    });
 });

src/test/converter2/behavior/includeTag/circularInclude.ts

@@ -0,0 +1,4 @@
+/**
+ * {@include includeTag.md#circular}
+ */
+export const circular = true;