Merge pull request #317 from josephjunker/allowlist-html-tags

Add allowlist for HTML tags and corresponding validation

Author: octogonz

common/changes/@microsoft/tsdoc-config/allowlist-html-tags_2022-04-05-21-35.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc-config",
+      "comment": "Add `supportedHtmlTags` and `reportUnsupportedHtmlTags` configuration options",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc-config",
+  "email": "josephjunker@users.noreply.github.com"
+}

common/changes/@microsoft/tsdoc/allowlist-html-tags_2022-04-05-21-35.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Add `supportedHtmlTags` and `reportUnsupportedHtmlTags` options and corresponding validation",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "josephjunker@users.noreply.github.com"
+}

tsdoc-config/src/TSDocConfigFile.ts

@@ -41,6 +41,8 @@ interface IConfigJson {
   noStandardTags?: boolean;
   tagDefinitions?: ITagConfigJson[];
   supportForTags?: { [tagName: string]: boolean };
+  supportedHtmlElements?: string[];
+  reportUnsupportedHtmlElements?: boolean;
 }
 
 /**
@@ -69,6 +71,8 @@ export class TSDocConfigFile {
   private readonly _tagDefinitions: TSDocTagDefinition[];
   private readonly _tagDefinitionNames: Set<string>;
   private readonly _supportForTags: Map<string, boolean>;
+  private _supportedHtmlElements: Set<string> | undefined;
+  private _reportUnsupportedHtmlElements: boolean | undefined;
 
   private constructor() {
     this.log = new ParserMessageLog();
@@ -167,6 +171,18 @@ export class TSDocConfigFile {
     return this._supportForTags;
   }
 
+  public get supportedHtmlElements(): ReadonlyArray<string> | undefined {
+    return this._supportedHtmlElements && Array.from(this._supportedHtmlElements);
+  }
+
+  public get reportUnsupportedHtmlElements(): boolean | undefined {
+    return this._reportUnsupportedHtmlElements;
+  }
+
+  public set reportUnsupportedHtmlElements(value: boolean | undefined) {
+    this._reportUnsupportedHtmlElements = value;
+  }
+
   /**
    * Removes all items from the `tagDefinitions` array.
    */
@@ -217,6 +233,23 @@ export class TSDocConfigFile {
     this._tagDefinitions.push(tagDefinition);
   }
 
+  /**
+   * Adds a new item to the `supportedHtmlElements` array.
+   */
+  public addSupportedHtmlElement(htmlElement: string): void {
+    if (!this._supportedHtmlElements) {
+      this._supportedHtmlElements = new Set();
+    }
+    this._supportedHtmlElements.add(htmlElement);
+  }
+
+  /**
+   * Removes the explicit list of allowed html elements.
+   */
+  public clearSupportedHtmlElements(): void {
+    this._supportedHtmlElements = undefined;
+  }
+
   /**
    * Removes all entries from the "supportForTags" map.
    */
@@ -334,6 +367,15 @@ export class TSDocConfigFile {
       });
     }
 
+    if (configJson.supportedHtmlElements) {
+      this._supportedHtmlElements = new Set();
+      for (const htmlElement of configJson.supportedHtmlElements) {
+        this.addSupportedHtmlElement(htmlElement);
+      }
+    }
+
+    this._reportUnsupportedHtmlElements = configJson.reportUnsupportedHtmlElements;
+
     if (configJson.supportForTags) {
       for (const tagName of Object.keys(configJson.supportForTags)) {
         const supported: boolean = configJson.supportForTags[tagName];
@@ -553,6 +595,12 @@ export class TSDocConfigFile {
       configFile.setSupportForTag(tagDefinition.tagName, true);
     }
 
+    for (const htmlElement of configuration.supportedHtmlElements) {
+      configFile.addSupportedHtmlElement(htmlElement);
+    }
+
+    configFile.reportUnsupportedHtmlElements = configuration.validation.reportUnsupportedHtmlElements;
+
     return configFile;
   }
 
@@ -591,6 +639,14 @@ export class TSDocConfigFile {
       });
     }
 
+    if (this.supportedHtmlElements) {
+      configJson.supportedHtmlElements = [...this.supportedHtmlElements];
+    }
+
+    if (this._reportUnsupportedHtmlElements !== undefined) {
+      configJson.reportUnsupportedHtmlElements = this._reportUnsupportedHtmlElements;
+    }
+
     return configJson;
   }
 
@@ -712,6 +768,16 @@ export class TSDocConfigFile {
         });
       }
     });
+
+    if (this.supportedHtmlElements) {
+      configuration.setSupportedHtmlElements([...this.supportedHtmlElements]);
+    }
+
+    if (this._reportUnsupportedHtmlElements === false) {
+      configuration.validation.reportUnsupportedHtmlElements = false;
+    } else if (this._reportUnsupportedHtmlElements === true) {
+      configuration.validation.reportUnsupportedHtmlElements = true;
+    }
   }
 
   private _getNoStandardTagsWithExtends(): boolean {