feat: allowlist for version numbers in YAML comments (#172)

* feat: allowlist for version numbers in YAML comments

If an environment variable `NODE_RELEASED_VERSIONS` is detected, it is
used to validate the version numbers in the YAML comments. At the
notable exception of version numbers 0.0.x and 0.1.x,  and the
`REPLACEME` placeholder, any value not in the list is reported as
invalid.

The idea is to use this in a GitHub Action. It will generally not affect
running the linter locally.

README.md

@@ -20,12 +20,34 @@ npm test
 
 ### Adding the language to the documentation style guide
 
-1. PR the [nodejs/node](https://github.com/nodejs/node) repo adding the language/grammar to the [documentation style guide](https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md)
+1. PR the [nodejs/node](https://github.com/nodejs/node) repo adding the
+   language/grammar to the
+   [documentation style guide](https://github.com/nodejs/node/blob/master/doc/guides/doc-style-guide.md).
 
 ### Adding the language to the linter
 
-1. PR this repo adding the language/grammar
-1. Bump this package version, publish it
-1. In [node-lint-md-cli-rollup](https://github.com/nodejs/node/tree/master/tools/node-lint-md-cli-rollup), bump the `remark-preset-lint-node` dependency 
-1. In the `nodejs/node` repo, rebuild the Markdown linter (`make lint-md-rollup`)
-1. PR the `nodejs/node` repo with the updated linter
+1. PR this repo adding the language/grammar.
+1. Bump this package version, publish it.
+1. In
+   [node-lint-md-cli-rollup](https://github.com/nodejs/node/tree/master/tools/node-lint-md-cli-rollup),
+   bump the `remark-preset-lint-node` dependency.
+1. In the `nodejs/node` repo, rebuild the Markdown linter
+   (`make lint-md-rollup`).
+1. PR the `nodejs/node` repo with the updated linter.
+
+## Environment variables
+
+#### `NODE_RELEASED_VERSIONS`
+
+On runtime, the linter will check the environment if the
+`NODE_RELEASED_VERSIONS` variable is defined; if it's there, it will use the
+content of the variable as a comma-separated list of allowed version numbers.
+This list is supposed to be built from the changelog(s), and validates the
+version numbers for the `nodejs-yaml-comments` rule.
+
+For better compatibility with the nodejs/node changelogs, there are a few
+exceptions:
+
+- Version numbers `^0.0.0 || ^0.1.0` are not validated using the provided list,
+  they are validating using the `vx.x.x` pattern.
+- `REPLACEME` placeholder is always valid, regardless it's in the list or not.

remark-lint-nodejs-yaml-comments.js

@@ -22,6 +22,17 @@ const validVersionNumberRegex = /^v\d+\.\d+\.\d+$/;
 const prUrlRegex = new RegExp("^https://github.com/nodejs/node/pull/\\d+$");
 const privatePRUrl = "https://github.com/nodejs-private/node-private/pull/";
 
+let releasedVersions;
+let invalidVersionMessage = "version(s) must respect the pattern `vx.x.x` or";
+if (process.env.NODE_RELEASED_VERSIONS) {
+  console.log("Using release list from env...");
+  releasedVersions = process.env.NODE_RELEASED_VERSIONS.split(",").map(
+    (v) => `v${v}`
+  );
+  invalidVersionMessage = `version not listed in the changelogs, `;
+}
+invalidVersionMessage += `use the placeholder \`${VERSION_PLACEHOLDER}\``;
+
 const kContainsIllegalKey = Symbol("illegal key");
 const kWrongKeyOrder = Symbol("Wrong key order");
 function unorderedKeys(meta) {
@@ -41,11 +52,16 @@ function containsInvalidVersionNumber(version) {
     return version.some(containsInvalidVersionNumber);
   }
 
-  return (
-    version !== undefined &&
-    version !== VERSION_PLACEHOLDER &&
-    !validVersionNumberRegex.test(version)
-  );
+  if (version === undefined || version === VERSION_PLACEHOLDER) return false;
+
+  if (
+    releasedVersions &&
+    // Always ignore 0.0.x and 0.1.x release numbers:
+    (version[1] !== "0" || (version[3] !== "0" && version[3] !== "1"))
+  )
+    return !releasedVersions.includes(version);
+
+  return !validVersionNumberRegex.test(version);
 }
 const getValidSemver = (version) =>
   version === VERSION_PLACEHOLDER ? MAX_SAFE_SEMVER_VERSION : version;
@@ -122,11 +138,7 @@ function validateChanges(file, node, changes) {
     }
 
     if (containsInvalidVersionNumber(change.version)) {
-      file.message(
-        `changes[${index}]: version(s) must respect the pattern \`vx.x.x\` ` +
-          `or use the placeholder \`${VERSION_PLACEHOLDER}\``,
-        node
-      );
+      file.message(`changes[${index}]: ${invalidVersionMessage}`, node);
     } else if (areVersionsUnordered(change.version)) {
       file.message(`changes[${index}]: list of versions is not in order`, node);
     }
@@ -180,31 +192,22 @@ function validateMeta(node, file, meta) {
   }
 
   if (containsInvalidVersionNumber(meta.added)) {
-    file.message(
-      "Invalid `added` value: version(s) must respect the pattern `vx.x.x` " +
-        `or use the placeholder \`${VERSION_PLACEHOLDER}\``,
-      node
-    );
+    file.message(`Invalid \`added\` value: ${invalidVersionMessage}`, node);
   } else if (areVersionsUnordered(meta.added)) {
     file.message("Versions in `added` list are not in order", node);
   }
 
   if (containsInvalidVersionNumber(meta.deprecated)) {
     file.message(
-      "Invalid `deprecated` value: version(s) must respect the pattern `vx.x.x` " +
-        `or use the placeholder \`${VERSION_PLACEHOLDER}\``,
+      `Invalid \`deprecated\` value: ${invalidVersionMessage}`,
       node
     );
   } else if (areVersionsUnordered(meta.deprecated)) {
     file.message("Versions in `deprecated` list are not in order", node);
   }
 
   if (containsInvalidVersionNumber(meta.removed)) {
-    file.message(
-      "Invalid `removed` value: version(s) must respect the pattern `vx.x.x` " +
-        `or use the placeholder \`${VERSION_PLACEHOLDER}\``,
-      node
-    );
+    file.message(`Invalid \`removed\` value: ${invalidVersionMessage}`, node);
   } else if (areVersionsUnordered(meta.removed)) {
     file.message("Versions in `removed` list are not in order", node);
   }