Permissions API permissions descriptions linter

docs/data-guidelines.md

@@ -120,6 +120,27 @@ For example, the `ImageData` API has worker support, recorded like this:
 
 Formerly named `available_in_workers`, this policy was set in [#2362](https://github.com/mdn/browser-compat-data/pull/2362).
 
+### Permissions API permission descriptions (`api.Permissions.*_permission.__compat.description`)
+
+Document Permissions API permissions called `[permissionname]` as `api.Permissions.[permissionname]_permission` and add a description that reads `"<code>[permissionname]</code> permission"`
+For example, the Geolocation permission is named `geolocation_permission` with the description text `<code>geolocation</code> permission`, like this:
+
+```
+{
+  "api": {
+    "Permissions": {
+      "__compat": { ... },
+      "geolocation_permission": {
+        "__compat": {
+          "description": "<code>geolocation</code> permission",
+          "support": { ... }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Non-functional defined names imply `partial_implementation`
 
 If a browser recognizes an API name, but the API doesn’t have any discernable behavior, use `"partial_implementation": true` instead of `"version_added": false`, as if the feature has non-standard support, rather than no support.

test/linter/test-descriptions.js

@@ -75,6 +75,29 @@ function hasCorrectWebWorkersDescription(apiData, apiName, logger) {
   }
 }
 
+/**
+ * @param {Identifier} apiData
+ * @param {String} apiName
+ * @param {Logger} logger
+ */
+function hasCorrectPermissionDescription(apiData, apiName, logger) {
+  const expectedDescrition = `<code>${apiName.replace(
+    '_permission',
+    '',
+  )}</code> permission`;
+  if (
+    apiName &&
+    apiName.match('_permission$') &&
+    apiData &&
+    apiData.__compat &&
+    apiData.__compat.description !== expectedDescrition
+  ) {
+    logger.error(chalk`{red Incorrect permission description for {bold ${apiName}}}
+      {yellow Actual: {bold "${apiData.__compat.description || ''}"}}
+      {green Expected: {bold "${expectedDescrition}"}}`);
+  }
+}
+
 /**
  * @param {string} filename
  */
@@ -101,6 +124,13 @@ function testDescriptions(filename) {
     }
   }
 
+  if (data.api && data.api.Permissions) {
+    for (const permissionKey in data.api.Permissions) {
+      const apiData = data.api.Permissions[permissionKey];
+      hasCorrectPermissionDescription(apiData, permissionKey, logger);
+    }
+  }
+
   if (errors.length) {
     console.error(
       chalk`{red   Descriptions – {bold ${errors.length}} ${