eslint-plugin-stratified-design 0.7.0 → 0.8.0-beta.1

package/README.md

@@ -39,4 +39,5 @@ Then configure the rules you wish to use under the rules section:
 ## Supported Rules
 
 - [lower-level-imports](https://github.com/anisotropy/eslint-plugin-stratified-design/blob/main/docs/rules/lower-level-imports.md): Requires lower-level modules to be imported.
+- [lower-level-imports](https://github.com/anisotropy/eslint-plugin-stratified-design/blob/main/docs/rules/stratified-imports.md): Requires lower-level modules to be imported. The stratified structure is set by `.stratified.json`.
 - [no-same-level-funcs](https://github.com/anisotropy/eslint-plugin-stratified-design/blob/main/docs/rules/no-same-level-funcs.md): Disallows calling functions in the same file.

package/docs/rules/lower-level-imports.md

@@ -15,9 +15,14 @@ This rule works correctly on POSIX systems, where the path segment separator is
 The syntax to specify the level structure is as follows:
 
 ```json
-"lower-level-imports": ["error", {
-  "structure": ["layer1", "layer2", "layer3"]
-}]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    {
+      "structure": ["layer1", "layer2", "layer3"]
+    }
+  ]
+}
 ```
 
 In the folder array, the file or folder on the left is considered to be at a higher level than the one on the right.
@@ -25,9 +30,14 @@ In the folder array, the file or folder on the left is considered to be at a hig
 To designate a layer as an abstract barrier, set `barrier` to `true`:
 
 ```json
-"lower-level-imports": ["error", {
-  "structure": ["layer1", { "name": "layer2", "barrier": true }, "layer3"],
-}]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    {
+      "structure": ["layer1", { "name": "layer2", "barrier": true }, "layer3"]
+    }
+  ]
+}
 ```
 
 For the 'abstract barrier,' refer to "[Grokking Simplicity](https://grokkingsimplicity.com)."
@@ -35,33 +45,54 @@ For the 'abstract barrier,' refer to "[Grokking Simplicity](https://grokkingsimp
 To locate a node module in the structure, set `nodeModule` to `true`:
 
 ```json
-"lower-level-imports": ["error", {
-  "structure": ["layer1", { "name": "nodeModule", "nodeModule": true }, "layer3"],
-}]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    {
+      "structure": [
+        "layer1",
+        { "name": "nodeModule", "nodeModule": true },
+        "layer3"
+      ]
+    }
+  ]
+}
 ```
 
 The default root directory is the current working directory. To change the root directory, use the `root` option:
 
 ```json
-"lower-level-imports": ["error", {
-  "structure": ["layer1", "layer2", "layer3"],
-  "root": "./src"
-}]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    {
+      "structure": ["layer1", "layer2", "layer3"],
+      "root": "./src"
+    }
+  ]
+}
 ```
 
 If the name of an imported module has an alias, register the alias using the `aliases` option:
 
 ```json
-"lower-level-imports": ["error", {
-  "structure": ["layer1", "layer2", "layer3"],
-  "aliases": { "@": "./src" }
-}]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    {
+      "structure": ["layer1", "layer2", "layer3"],
+      "aliases": { "@": "./src" }
+    }
+  ]
+}
 ```
 
 If you want to register the level of a layer by 'number,' set the option `useLevelNumber` to `true`:
 
 ```json
-"lower-level-imports": ["error", { "useLevelNumber": true }]
+{
+  "stratified-design/lower-level-imports": ["error", { "useLevelNumber": true }]
+}
 ```
 
 The options `structure` and `useLevelNumber` can be used together.
@@ -69,13 +100,20 @@ The options `structure` and `useLevelNumber` can be used together.
 An `index.xxx` file can be the highest level layer of sibling files when the option `isIndexHighest` is set to `true`:
 
 ```json
-"lower-level-imports": ["error", { "isIndexHighest": true }]
+{
+  "stratified-design/lower-level-imports": ["error", { "isIndexHighest": true }]
+}
 ```
 
 You can register the files to apply the rule (`lower-level-imports`) using the `include` and `exclude` options:
 
 ```json
-"lower-level-imports": ["error", { "include": ["**/*.js"], "exclude": ["**/*.test.js"] }]
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    { "include": ["**/*.js"], "exclude": ["**/*.test.js"] }
+  ]
+}
 ```
 
 The default is as follows:

package/docs/rules/no-same-level-funcs.md

@@ -7,7 +7,12 @@ This rule prohibits calling functions at the same level in the same file.
 You can register the files to apply the rule (`no-same-level-funcs`) using the `include` and `exclude` options:
 
 ```json
-"no-same-level-funcs": ["error", { "include": ["**/*.js"], "exclude": ["**/*.test.js"] }]
+{
+  "stratified-design/no-same-level-funcs": [
+    "error",
+    { "include": ["**/*.js"], "exclude": ["**/*.test.js"] }
+  ]
+}
 ```
 
 The default is as follows:

package/docs/rules/stratified-imports.md

@@ -0,0 +1,178 @@
+# Require that lower-level modules be imported (stratified-imports)
+
+(Note: This rule works correctly on POSIX systems, where the path segment separator is `/`. It will be updated to work well on Windows systems in the future.)
+
+This rule enforces the requirement for importing lower-level modules. The hierarchy should be set by `.stratified.json` in **each folder** as follows:
+
+```json
+[
+  ["layerA"],
+  [{ "name": "layerB", "barrier": true }],
+  [{ "name": "nodeModuleC", "nodeModule": true }],
+  ["layerD", "layerE"]
+]
+```
+
+And consider that the folder structure is as follows:
+
+```
+ ┣ layerA
+ ┣ layerB
+ ┣ layerD
+ ┣ layerE
+ ┃ ┣ index.js
+ ┃ ┣ entry
+ ┃ ┣ layerEA
+ ┃ ┗ .stratified.json
+ ┗ .stratified.json
+```
+
+The above JSON file indicates the following:
+
+- The `layerA` file/folder at the highest level.
+- The `layerB` file/folder is a lower-level layer than `layerA` and serves as an abstract barrier. (For the concept of 'abstract barrier,' refer to '[Grokking Simplicity](https://grokkingsimplicity.com).')
+- `nodeModuleC` is an **installed module** (node module) and is at a lower level than `layerB`. (Unregistered node modules are considered to be the lowest layers.)
+- The `layerD` file/folder and the `layerE` file/folder are at the same level and represent the lowest level layers.
+
+Consider that the `.stratified.json` in the `layerE` folder is as follows:
+
+```json
+[["index", "entry"], ["layerEA"]]
+```
+
+Higher-level layers than `layerE` can import `./layerE` and `./layer/entry` as follows:
+
+```js
+import { func } from "./layerE";
+import { func } from "./layerE/entry";
+```
+
+However, `./layer/layerEA` should not be imported.
+
+## Options
+
+If an imported module has an alias, register the alias using the `aliases` option:
+
+```json
+{
+  "stratified-design/stratified-imports": [
+    "error",
+    {
+      "aliases": { "@/": "./src/" }
+    }
+  ]
+}
+```
+
+You can register the files to which the rule (`stratified-imports`) should apply using the `include` and `exclude` options:
+
+```json
+{
+  "stratified-design/lower-level-imports": [
+    "error",
+    { "include": ["**/*.js"], "exclude": ["**/*.test.js"] }
+  ]
+}
+```
+
+The default configuration is as follows:
+
+```json
+{
+  "include": ["**/*.{js,ts,jsx,tsx}"],
+  "exclude": ["**/*.{spec,test}.{js,ts,jsx,tsx}"]
+}
+```
+
+## Rule Details
+
+Consider the following folder structure:
+
+```
+src/
+ ┣ layerA.js
+ ┣ layerB.js
+ ┣ layerD.js
+ ┣ layerE/
+ ┃ ┣ index.js
+ ┃ ┣ entry
+ ┃ ┣ layerEA.js
+ ┃ ┗ .stratified.json
+ ┗ .stratified.json
+```
+
+and the `.stratified.json` in `src/` is as follows:
+
+```json
+[
+  ["layerA"],
+  [{ "name": "layerB", "barrier": true }],
+  [{ "name": "nodeModuleC", "nodeModule": true }],
+  ["layerD", "layerE"]
+]
+```
+
+and the `.stratified.json` in `layerE/` is as follows:
+
+```json
+[["index", "entry"], ["layerEA"]]
+```
+
+Examples of **incorrect** code for this rule:
+
+```js
+// ./layerB.js
+import { func } from "./layerA";
+```
+
+```js
+// ./layerA.js
+import { func } from "./layerD";
+```
+
+```js
+// ./layerD.js
+import { func } from "nodeModuleC";
+```
+
+```js
+// ./layerD.js
+import { func } from "layerE";
+```
+
+```js
+// ./layerB.js
+import { func } from "layerE/layerEA";
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// ./layerA.js
+import { func } from "./layerB";
+```
+
+```js
+// ./layerB.js
+import { func } from "nodeModuleC";
+```
+
+```js
+// ./layerD.js
+import { func } from "some-node-module";
+```
+
+```js
+// ./layerB.js
+import { func } from "./layerD";
+```
+
+```js
+// ./layerB.js
+import { func } from "./layerE";
+```
+
+```js
+// ./layerB.js
+import { func } from "./layerE/entry";
+```

package/lib/helpers/{lowerLevelImports/4 layer.js → common.js}

@@ -1,5 +1,6 @@
 const p = require("path");
 
+// @level 2
 /**
  * @param {string} from
  * @param {string} to
@@ -10,27 +11,34 @@ const toRelative = (from, to) => {
   return `${to}/`.startsWith(`${from}/`) ? `./${rel}` : rel;
 };
 
+// @level 2
 /**
  * @param {string} path
  * @returns path to segments
  */
 const toSegments = (path) => path.split("/");
 
+// @level 2
 /**
  * @param {string[]} segments
  * @returns segments to path
  */
 const toPath = (segments) => segments.join("/");
 
+// @level 2
 const joinPath = p.join;
 
+// @level 2
 const resolvePath = p.resolve;
 
+// @level 2
 const parsePath = p.parse;
 
+// @level 2
 /**
- * @param {any[]} array
- * @param {(item: any) => boolean} callback
+ * @template T
+ * @param {T[]} array
+ * @param {(item: T) => boolean} callback
  * @returns {number}
  */
 const findLastIndex = (array, callback) => {
@@ -41,6 +49,7 @@ const findLastIndex = (array, callback) => {
   }, -1);
 };
 
+// @level 2
 /**
  * @param {any[]} array1
  * @param {any[]} array2
@@ -49,6 +58,29 @@ const equal = (array1, array2) => {
   return array1.every((item, index) => item === array2[index]);
 };
 
+// @level 2
+/**
+ * @template T
+ * @param {T[]} array
+ * @param {number} index
+ * @returns {T}
+ */
+const readArray = (array, index) => {
+  return index >= 0 ? array[index] : array[array.length + index];
+};
+
+// @level 1
+/**
+ * @param {string} path
+ * @return {string[]}
+ */
+const reducedPaths = (path) => {
+  return toSegments(path).reduce((paths, _, index, segments) => {
+    paths.push(toPath(segments.slice(0, segments.length - index)));
+    return paths;
+  }, []);
+};
+
 module.exports = {
   toRelative,
   toSegments,
@@ -58,4 +90,6 @@ module.exports = {
   parsePath,
   findLastIndex,
   equal,
+  readArray,
+  reducedPaths,
 };

package/lib/helpers/lowerLevelImports/1 layer.js

@@ -3,7 +3,7 @@ const { report: reportError } = require("./2 layer");
 const {
   isNodeModule,
   findLevel: findLayerLevel,
-  hasInterface: hasInterfaceBetween,
+  hasBarrier: hasBarrierBetween,
   removeAlias: removeAliasFromModuleSource,
 } = require("./3 layer");
 const {
@@ -12,14 +12,14 @@ const {
   toPath,
   resolvePath,
   parsePath,
-} = require("./4 layer");
+} = require("../common");
 
 const FINISHED = "finished";
 
 /**
  *
  * @param {string} cwd
- * @param {*} options
+ * @param {import("./3 layer").Options} options
  * @returns
  */
 const createRootDir = (cwd, options) => {
@@ -27,7 +27,7 @@ const createRootDir = (cwd, options) => {
 };
 
 /**
- * @param {*} options
+ * @param {import("./3 layer").Options} options
  * @param {string} contextFileSource
  */
 const parseFileSource = (options, contextFileSource) => {
@@ -50,10 +50,11 @@ const parseFileSource = (options, contextFileSource) => {
 
 /**
  * @param {string} cwd
+ * @param {string[]} excludeImports
  * @param {string} fileDir
  * @param {{alias: string, path: string}[]} aliases
  */
-const createModulePath = (cwd, fileDir, aliases) => {
+const createModulePath = (cwd, excludeImports, fileDir, aliases) => {
   const removeAlias = removeAliasFromModuleSource(cwd, fileDir, aliases);
   /**
    * @param {string} moduleSourceWithAlias
@@ -61,12 +62,18 @@ const createModulePath = (cwd, fileDir, aliases) => {
   return (moduleSourceWithAlias) => {
     const moduleSource = removeAlias(moduleSourceWithAlias);
     const isNodeModule = moduleSource.startsWith(".") === false;
-    return isNodeModule ? moduleSource : resolvePath(fileDir, moduleSource);
+    const modulePath = isNodeModule
+      ? moduleSource
+      : resolvePath(fileDir, moduleSource);
+    const isModuleExcluded = Boolean(
+      excludeImports.find((pattern) => minimatch(modulePath, pattern))
+    );
+    return { modulePath, isModuleExcluded };
   };
 };
 
 /**
- * @param {*} options
+ * @param {import("./3 layer").Options} options
  * @param {string} fileDor
  * @param {string} modulePath
  */
@@ -82,7 +89,7 @@ const isFileIndexOfModule = (options, fileDir, filePath) => (modulePath) => {
 /**
  * Report error about using `options.useLevelNumber`
  * @param {import('eslint').Rule.RuleContext} context
- * @param {*} options
+ * @param {import("./3 layer").Options} options
  * @param {string} rootDir
  * @param {string} filePath
  */
@@ -191,10 +198,10 @@ const reportHasProperLevel = (
   filePath
 ) => {
   const findLevel = findLayerLevel(structure);
-  const hasInterface = hasInterfaceBetween(structure, fileLevel);
+  const hasBarrier = hasBarrierBetween(structure, fileLevel);
 
   /**
-   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {import('../type').Node} node
    * @param {string} modulePath
    */
   return (node, modulePath) => {
@@ -222,7 +229,7 @@ const reportHasProperLevel = (
       return FINISHED;
     }
 
-    if (hasInterface(moduleLevel)) {
+    if (hasBarrier(moduleLevel)) {
       report("barrier");
       return FINISHED;
     }

package/lib/helpers/lowerLevelImports/2 layer.js

@@ -1,15 +1,15 @@
 const { isNodeModule } = require("./3 layer");
-const { toRelative } = require("./4 layer");
+const { toRelative } = require("../common");
 
 /**
  * Report eslint error
- * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('../type.js').Context} context
  * @param {string} rootDir
- * * @param {string} filePath
+ * @param {string} filePath
  */
 const report = (context, rootDir, filePath) => {
   /**
-   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {import('../type').Node} node
    * @param {string} messageId
    * @param {string} modulePath
    */

package/lib/helpers/lowerLevelImports/3 layer.js

@@ -4,11 +4,36 @@ const {
   joinPath,
   resolvePath,
   toRelative,
-} = require("./4 layer");
+} = require("../common");
 
 /**
- * @param {*} options
+ * @typedef {{
+ *  structure: Array<
+ *    string | { name: string, barrier?: boolean, interface?: boolean, nodeModule?: boolean, isNodeModule?: boolean }
+ *  >,
+ *  root: string,
+ *  aliases: Record<string, string>,
+ *  exclude: string[],
+ *  include: string[],
+ *  useLevelNumber: boolean
+ *  isIndexHighest: boolean
+ * }} Options
+ */
+
+/**
+ * @typedef {{
+ *  name: string;
+ *  barrier?: boolean | undefined;
+ *  interface?: boolean | undefined;
+ *  nodeModule?: boolean | undefined;
+ *  isNodeModule?: boolean | undefined;
+ * }[]} Structure
+ */
+
+/**
+ * @param {Options} options
  * @param {string} rootDir
+ * @returns {Structure}
  */
 const createStructure = (options, rootDir) => {
   return options.structure.map((layer) => {
@@ -20,7 +45,7 @@ const createStructure = (options, rootDir) => {
 };
 
 /**
- * @param {*} options
+ * @param {Options} options
  */
 const createAliases = (options) => {
   return Object.keys(options.aliases)
@@ -63,7 +88,7 @@ const isNodeModule = (rootDir) => {
 
 /**
  * Find the layer level for a module
- * @param {{[string]: {name: string; nodeModule: boolean; barrier: boolean; isNodeModule: boolean, interface: boolean}}} structure
+ * @param {Structure} structure
  * @returns the level of the module with `path`
  */
 const findLevel = (structure) => {
@@ -83,25 +108,25 @@ const findLevel = (structure) => {
 
 /**
  * Check if there is an interface between file layer and module layer
- * @param {{[string]: {name: string; nodeModule: boolean; barrier: boolean; isNodeModule: boolean, interface: boolean}}} structure
+ * @param {Structure} structure
  * @param {number} fileLevel
  */
-const hasInterface = (structure, fileLevel) => {
+const hasBarrier = (structure, fileLevel) => {
   /**
    * @param {number} moduleLevel
    */
   return (moduleLevel) => {
-    const layerInterface = structure
+    const layerBarrier = structure
       .slice(fileLevel + 1, moduleLevel)
       .find((layer) => layer.barrier || layer.interface);
-    return Boolean(layerInterface);
+    return Boolean(layerBarrier);
   };
 };
 
 module.exports = {
   isNodeModule,
   findLevel,
-  hasInterface,
+  hasBarrier,
   createStructure,
   createAliases,
   removeAlias,