Linter: New Rule (DPW005) for Code Samples

.markdownlint-cli2.cjs

@@ -5,5 +5,6 @@ module.exports = {
     './.markdownlint/customRules/rules/md-images',
     './.markdownlint/customRules/rules/html-links',
     './.markdownlint/customRules/rules/md-links',
+    './.markdownlint/customRules/rules/code-samples', 
   ]
 };

.markdownlint/customRules/rules/code-samples.js

@@ -0,0 +1,59 @@
+/**
+ * @fileOverview Custom rule for code sample validation.
+ * 
+ * This rule expects MD files in the `docs` dir, and code samples files
+ * present as sibling directory of `docs` dir. The struct is is:
+ * -- project
+ *   -- docs
+ *   -- code-samples
+ *   -- mdx_includes
+ * 
+ * The pattern is `/{!>\s*(.+?)\s*(\[.+])?\s*!}/g` which matches:
+ *  - {!>code-samples/messaging/code-snippets/send-a2p-sms.rb!}
+ *  - {!>    code-samples/messaging/code-snippets/send-a2p-sms.rb    !} 
+ *  - {!> code-samples/messaging/code-snippets/send-a2p-sms.py !}
+ *  - {!> code-samples/messaging/code-snippets/send-a2p-sms.php [ln:2-]!}
+ *  - {!> mdx_includes/rcv-sdk-quick-start-js.md !} 
+ */
+const { pathToFileURL } = require("url");
+const fs = require("fs");
+const path = require("path");
+const { addError } = require("../helpers");
+
+module.exports = {
+  names: ["DPW005"],
+  description: "Code samples validation",
+  tags: ["custom"],
+  function: function rule(params, onError) {
+    const pattern = /{!>\s*(.+?)\s*(\[.+])?\s*!}/g;
+    const rootPath = params.name.split("/docs/")[0];
+
+    params.tokens
+      .filter((token) => {
+        return (
+          token.type === "inline" ||
+          token.type === "fence" ||
+          token.type === "code_block"
+        );
+      })
+      .forEach((token) => {
+        let match;
+
+        while ((match = pattern.exec(token.content)) !== null) {
+          const fileName = match[1];
+
+          if (!fileName) {
+            addError(onError, token.lineNumber, `Code sample is empty`);
+          } else {
+            const filePath = path.join(rootPath, fileName);
+            const fileUrl = pathToFileURL(filePath);
+
+            if (!fs.existsSync(fileUrl)) {
+              const detail = `Not Exist: "${fileName}"`;
+              addError(onError, token.lineNumber, detail);
+            }
+          }
+        }
+      });
+  },
+};

.markdownlint/rules/ci.cjs

@@ -0,0 +1,18 @@
+/**
+ * @fileOverview Rules used by CI (Jenkins or Github Actions)
+ * 
+ * Disabled: all built-in rules.
+ * Enabled:  custom rules - DPW001, DPW002, DPW003, DPW004.
+ * 
+ * Rules enabled in this file are considered as "Strict" rules.
+ * "Strict" means if any rule was not pass, it will block CI workflow.
+ */
+
+module.exports = {
+  "default": false,
+  "DPW001": true,
+  "DPW002": true,
+  "DPW003": true,
+  "DPW004": true,
+  "DPW005": true,
+};

.markdownlint/rules/index.cjs

@@ -1,10 +1,3 @@
-module.exports = process.env.NODE_ENV === 'cli' ? {
-  "default": false,
-  "DPW001": true,
-  "DPW002": true,
-  "DPW003": true,
-} : {
-  "default": true,
-  "MD013": false,
-  "MD033": false,
-};
+module.exports = process.env.NODE_ENV === 'cli' 
+  ? require('./ci.cjs') 
+  : require('./vscode.cjs');

.markdownlint/rules/vscode.cjs

@@ -0,0 +1,23 @@
+/**
+ * @fileOverview Rules used by Visual Studio Code.
+ * 
+ * Enabled: all built-in rules AND custom rules.
+ * 
+ * To disable some rule by appending it to the end. 
+ * 
+ * For example, to disable `MD045` by appending:
+ * 
+ * "MD045": false,
+ * 
+ * Or to customize some rule by:
+ * 
+ * "MD004": {
+ *   "style": "asterisk"
+ * }
+ */
+
+module.exports = {
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+};