eslint-plugin-boundaries 2.6.0 → 2.9.0

package/README.md

@@ -259,9 +259,9 @@ Some rules require extra configuration, and it has to be defined in each specifi
 
 #### Main format of rules options
 
-The docs of each rule contains an specification of their own options, but __the main rules share the format in which the options have to be defined__. The format described here is valid for options of [`element-types`](docs/rules/element-types.md), [`external`](docs/rules/external.md) and [`entry-point`](docs/rules/entry-point.md) rules, __except the `message` properties, which for the moment are only supported in the [`element-types`](docs/rules/element-types.md) rule settings.
+The docs of each rule contains an specification of their own options, but __the main rules share the format in which the options have to be defined__. The format described here is valid for options of [`element-types`](docs/rules/element-types.md), [`external`](docs/rules/external.md) and [`entry-point`](docs/rules/entry-point.md) rules.
 
-Options set an "allow/disallow" value by default, and provide an array of rules. Each matching rule will override the default value and the value returned by previous matching rules. So, the final result of the options, once processed for each case, will be "allow" or "disallow", and this value will be applied by the plugin rule in the correspondant way, making it to produce an eslint error or not.
+Options set an `allow` or `disallow` value by default, and provide an array of rules. Each matching rule will override the default value and the value returned by previous matching rules. So, the final result of the options, once processed for each case, will be `allow` or `disallow`, and this value will be applied by the plugin rule in the correspondant way, making it to produce an eslint error or not.
 
 ```jsonc
 {
@@ -300,7 +300,7 @@ Remember that:
 
 * __`from/target`__: `<element matchers>` Depending of the rule to which the options are for, the rule will be applied only if the file being analized matches with this element matcher (`from`), or the dependency being imported matches with this element matcher (`target`).
 * __`disallow/allow`__: `<value matchers>` If the plugin rule target matches with this, then the result of the rule will be "disallow/allow". Each rule will require a type of value here depending of what it is checking. In the case of the `element-types` rule, for example, another `<element matcher>` has to be provided in order to check the type of the local dependency.
-* __`message`__: `<string>` Optional. If the rule results in an error, the plugin will return this message.
+* __`message`__: `<string>` Optional. If the rule results in an error, the plugin will return this message instead of the default one. Read [error messages](#error-messages) for further info.
 
 > Tip: Properties `from/target` and `disallow/allow` can receive a single matcher, or an array of matchers.
 
@@ -317,7 +317,7 @@ Elements matchers used in the rules options can have the next formats:
 
 The plugin returns a different default message for each rule, check the documentation of each one for further info. But some rules support defining custom messages in their configuration, as seen in ["Main format of rules options"](#main-format-of-rules-options).
 
-When defining custom messages, it is possible to provide information about the type or captured properties of the current file or dependency. Use `${file.PROPERTY}` or `${dependency.PROPERTY}`, and it will be replaced by the correspondent captured value from the file or the dependency:
+When defining custom messages, it is possible to provide information about the current file or dependency. Use `${file.PROPERTY}` or `${dependency.PROPERTY}`, and it will be replaced by the correspondent captured value from the file or the dependency:
 
 ```jsonc
 {
@@ -327,8 +327,24 @@ When defining custom messages, it is possible to provide information about the t
 }
 ```
 
+Available properties in error templates both from `file` or `dependency` are:
+
+* `type`: Element's type.
+* `internalPath`: File path being analyzed or imported. Relative to the element's root path.
+* `source`: Available only for `dependency`. The source of the `import` statement as it is in the code.
+* `parent`: If the element is child of another element, it is also available in this property, which contains correspondent `type`, `internalPath` and captured properties as well.
+* ...All captured properties are also available
+
 > Tip: Read ["Global settings"](#global-settings) for further info about how to capture values from elements.
 
+Some rules also provide extra information about the reported error. For example, `no-external` rules provides information about detected forbidden specifiers. This information is available using `${report.PROPERTY}`. Check each rule's documentation to know which report properties it provides:
+
+```jsonc
+{
+  "message": "Do not import ${report.specifiers} from ${dependency.source} in helpers"
+}
+```
+
 ##### Advanced example of a rule configuration
 
 Just to illustrate the high level of customization that the plugin supports, here is an example of advanced options for the `boundaries/element-types` rule based on the previous global `elements` settings example:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-boundaries",
-  "version": "2.6.0",
+  "version": "2.9.0",
   "description": "Eslint plugin checking architecture boundaries between elements",
   "keywords": [
     "eslint",
@@ -32,21 +32,21 @@
   },
   "dependencies": {
     "eslint-import-resolver-node": "0.3.6",
-    "eslint-module-utils": "2.7.1",
+    "eslint-module-utils": "2.7.3",
     "chalk": "4.1.2",
-    "is-core-module": "2.8.0",
+    "is-core-module": "2.8.1",
     "micromatch": "4.0.4"
   },
   "devDependencies": {
     "cross-env": "7.0.3",
-    "eslint": "8.2.0",
-    "eslint-config-prettier": "8.3.0",
+    "eslint": "8.9.0",
+    "eslint-config-prettier": "8.4.0",
     "eslint-plugin-prettier": "4.0.0",
     "husky": "7.0.4",
     "is-ci": "3.0.1",
-    "jest": "27.3.1",
-    "lint-staged": "11.2.6",
-    "prettier": "2.4.1"
+    "jest": "27.5.1",
+    "lint-staged": "12.3.4",
+    "prettier": "2.5.1"
   },
   "lint-staged": {
     "test/**/*.js": "eslint",

package/src/helpers/messages.js

@@ -79,12 +79,36 @@ function ruleElementMessage(elementPatterns, elementCapturedValues) {
   return elementMatcherMessage(elementPatterns, elementCapturedValues);
 }
 
-function customErrorMessage(message, file, dependency) {
-  return replaceObjectValuesInTemplates(
-    replaceObjectValuesInTemplates(message, { ...file.capturedValues, type: file.type }, "file"),
-    { ...dependency.capturedValues, type: dependency.type },
+function elementPropertiesToReplaceInTemplate(element) {
+  return {
+    ...element.capturedValues,
+    type: element.type,
+    internalPath: element.internalPath,
+    source: element.source,
+  };
+}
+
+function customErrorMessage(message, file, dependency, report = {}) {
+  let replacedMessage = replaceObjectValuesInTemplates(
+    replaceObjectValuesInTemplates(message, elementPropertiesToReplaceInTemplate(file), "file"),
+    elementPropertiesToReplaceInTemplate(dependency),
     "dependency"
   );
+  if (file.parents[0]) {
+    replacedMessage = replaceObjectValuesInTemplates(
+      replacedMessage,
+      elementPropertiesToReplaceInTemplate(file.parents[0]),
+      "file.parent"
+    );
+  }
+  if (dependency.parents[0]) {
+    replacedMessage = replaceObjectValuesInTemplates(
+      replacedMessage,
+      elementPropertiesToReplaceInTemplate(dependency.parents[0]),
+      "dependency.parent"
+    );
+  }
+  return replaceObjectValuesInTemplates(replacedMessage, report, "report");
 }
 
 function elementCapturedValuesMessage(capturedValues) {

package/src/helpers/validations.js

@@ -42,12 +42,15 @@ function elementsMatcherSchema(matcherOptions = DEFAULT_MATCHER_OPTIONS) {
   };
 }
 
-function rulesOptionsSchema(options) {
+function rulesOptionsSchema(options = {}) {
   const mainKey = rulesMainKey(options.rulesMainKey);
-  const schema = [
+  return [
     {
       type: "object",
       properties: {
+        message: {
+          type: "string",
+        },
         default: {
           type: "string",
           enum: ["allow", "disallow"],
@@ -60,6 +63,9 @@ function rulesOptionsSchema(options) {
               [mainKey]: elementsMatcherSchema(),
               allow: elementsMatcherSchema(options.targetMatcherOptions),
               disallow: elementsMatcherSchema(options.targetMatcherOptions),
+              message: {
+                type: "string",
+              },
             },
             additionalProperties: false,
             anyOf: [
@@ -79,17 +85,6 @@ function rulesOptionsSchema(options) {
       additionalProperties: false,
     },
   ];
-  if (options.customMessage) {
-    schema[0].properties.message = {
-      type: "string",
-    };
-  }
-  if (options.customRuleMessage) {
-    schema[0].properties.rules.items.properties.message = {
-      type: "string",
-    };
-  }
-  return schema;
 }
 
 function isValidElementTypesMatcher(matcher, settings) {

package/src/rules/element-types.js

@@ -42,10 +42,7 @@ module.exports = dependencyRule(
   {
     ruleName: RULE_ELEMENT_TYPES,
     description: `Check allowed dependencies between element types`,
-    schema: rulesOptionsSchema({
-      customMessage: true,
-      customRuleMessage: true,
-    }),
+    schema: rulesOptionsSchema(),
   },
   function ({ dependency, file, node, context, options }) {
     if (dependency.isLocal && !dependency.isIgnored && dependency.type && !dependency.isInternal) {

package/src/rules/entry-point.js

@@ -8,6 +8,7 @@ const {
   isMatchElementKey,
   elementRulesAllowDependency,
 } = require("../helpers/rules");
+const { customErrorMessage, ruleElementMessage, elementMessage } = require("../helpers/messages");
 
 function isMatchElementInternalPath(elementInfo, matcher, options) {
   return isMatchElementKey(elementInfo, matcher, options, "internalPath");
@@ -20,7 +21,23 @@ function elementRulesAllowEntryPoint(element, dependency, options) {
     options,
     isMatch: isMatchElementInternalPath,
     rulesMainKey: "target",
-  }).result;
+  });
+}
+
+function errorMessage(ruleData, file, dependency) {
+  const ruleReport = ruleData.ruleReport;
+  if (ruleReport.message) {
+    return customErrorMessage(ruleReport.message, file, dependency);
+  }
+  if (ruleReport.isDefault) {
+    return `No rule allows the entry point '${
+      dependency.internalPath
+    }' in dependencies ${elementMessage(dependency)}`;
+  }
+  return `The entry point '${dependency.internalPath}' is not allowed in ${ruleElementMessage(
+    ruleReport.element,
+    dependency.capturedValues
+  )}. Disallowed in rule ${ruleReport.index + 1}`;
 }
 
 module.exports = dependencyRule(
@@ -32,17 +49,15 @@ module.exports = dependencyRule(
     }),
   },
   function ({ dependency, file, node, context, options }) {
-    if (
-      !dependency.isIgnored &&
-      dependency.type &&
-      !dependency.isInternal &&
-      !elementRulesAllowEntryPoint(file, dependency, options)
-    ) {
-      context.report({
-        message: `Entry point '${dependency.internalPath}' is not allowed in '${dependency.type}'`,
-        node: node,
-        ...dependencyLocation(node, context),
-      });
+    if (!dependency.isIgnored && dependency.type && !dependency.isInternal) {
+      const ruleData = elementRulesAllowEntryPoint(file, dependency, options);
+      if (!ruleData.result) {
+        context.report({
+          message: errorMessage(ruleData, file, dependency),
+          node: node,
+          ...dependencyLocation(node, context),
+        });
+      }
     }
   },
   {

package/src/rules/external.js

@@ -6,6 +6,7 @@ const dependencyRule = require("../rules-factories/dependency-rule");
 
 const { rulesOptionsSchema } = require("../helpers/validations");
 const { dependencyLocation, elementRulesAllowDependency } = require("../helpers/rules");
+const { customErrorMessage, ruleElementMessage, elementMessage } = require("../helpers/messages");
 
 function specifiersMatch(specifiers, options) {
   const importedSpecifiersNames = specifiers
@@ -44,6 +45,32 @@ function elementRulesAllowExternalDependency(element, dependency, options) {
   });
 }
 
+function errorMessage(ruleData, file, dependency) {
+  const ruleReport = ruleData.ruleReport;
+  if (ruleReport.message) {
+    return customErrorMessage(ruleReport.message, file, dependency, {
+      specifiers: ruleData.report && ruleData.report.join(", "),
+    });
+  }
+  if (ruleReport.isDefault) {
+    return `No rule allows the usage of external module '${
+      dependency.baseModule
+    }' in elements ${elementMessage(file)}`;
+  }
+
+  const fileReport = `is not allowed in ${ruleElementMessage(
+    ruleReport.element,
+    file.capturedValues
+  )}. Disallowed in rule ${ruleReport.index + 1}`;
+
+  if (ruleData.report) {
+    return `Usage of '${ruleData.report.join(", ")}' from external module '${
+      dependency.baseModule
+    }' ${fileReport}`;
+  }
+  return `Usage of external module '${dependency.baseModule}' ${fileReport}`;
+}
+
 module.exports = dependencyRule(
   {
     ruleName: RULE_EXTERNAL,
@@ -65,27 +92,17 @@ module.exports = dependencyRule(
   },
   function ({ dependency, file, node, context, options }) {
     if (dependency.isExternal) {
-      const isAllowed = elementRulesAllowExternalDependency(
+      const ruleData = elementRulesAllowExternalDependency(
         file,
         { ...dependency, specifiers: node.source.parent.specifiers },
         options
       );
-      if (!isAllowed.result) {
-        if (isAllowed.report) {
-          context.report({
-            message: `Usage of '${isAllowed.report.join(", ")}' from external module '${
-              dependency.baseModule
-            }' is not allowed in '${file.type}'`,
-            node: node,
-            ...dependencyLocation(node, context),
-          });
-        } else {
-          context.report({
-            message: `Usage of external module '${dependency.baseModule}' is not allowed in '${file.type}'`,
-            node: node,
-            ...dependencyLocation(node, context),
-          });
-        }
+      if (!ruleData.result) {
+        context.report({
+          message: errorMessage(ruleData, file, dependency),
+          node: node,
+          ...dependencyLocation(node, context),
+        });
       }
     }
   },

package/src/rules/no-private.js

@@ -3,6 +3,14 @@ const { RULE_NO_PRIVATE } = require("../constants/settings");
 const dependencyRule = require("../rules-factories/dependency-rule");
 
 const { dependencyLocation } = require("../helpers/rules");
+const { customErrorMessage, elementMessage } = require("../helpers/messages");
+
+function errorMessage(file, dependency, options) {
+  if (options.message) {
+    return customErrorMessage(options.message, file, dependency);
+  }
+  return `Dependency is private of element ${elementMessage(dependency.parents[0])}`;
+}
 
 module.exports = dependencyRule(
   {
@@ -15,12 +23,15 @@ module.exports = dependencyRule(
           allowUncles: {
             type: "boolean",
           },
+          message: {
+            type: "string",
+          },
         },
         additionalProperties: false,
       },
     ],
   },
-  function ({ dependency, node, context, options }) {
+  function ({ file, dependency, node, context, options }) {
     if (
       !dependency.isIgnored &&
       dependency.isLocal &&
@@ -32,7 +43,7 @@ module.exports = dependencyRule(
       (!options || !options.allowUncles || dependency.relationship !== "uncle")
     ) {
       context.report({
-        message: `Dependency is private of another element`,
+        message: errorMessage(file, dependency, options),
         node: node,
         ...dependencyLocation(node, context),
       });