eslint-plugin-stratified-design 0.8.0-beta → 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/common.js

@@ -1,5 +1,6 @@
 const p = require("path");
 
+// @level 2
 /**
  * @param {string} from
  * @param {string} to
@@ -10,24 +11,30 @@ 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
 /**
  * @template T
  * @param {T[]} array
@@ -42,6 +49,7 @@ const findLastIndex = (array, callback) => {
   }, -1);
 };
 
+// @level 2
 /**
  * @param {any[]} array1
  * @param {any[]} array2
@@ -50,6 +58,7 @@ const equal = (array1, array2) => {
   return array1.every((item, index) => item === array2[index]);
 };
 
+// @level 2
 /**
  * @template T
  * @param {T[]} array
@@ -60,6 +69,18 @@ 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,
@@ -70,4 +91,5 @@ module.exports = {
   findLastIndex,
   equal,
   readArray,
+  reducedPaths,
 };

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

@@ -19,7 +19,7 @@ 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
  */

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

@@ -1,56 +1,64 @@
 "use strict";
 
-const {
-  resolvePath,
-  joinPath,
-  toSegments,
-  readArray,
-  findLastIndex,
-} = require("../common");
+const { minimatch } = require("minimatch");
+const { resolvePath, reducedPaths, parsePath } = require("../common");
 const {
   toStructure,
   replaceAlias,
   readRawStructure,
   findLevel,
-  findLayerWithSimilarPath,
+  findLayerWithReducedPath,
+  readStructure,
+  hasBarrier,
+  isNotRegisteredNodeModule,
 } = require("./2 layer");
 
+const SUCCESS = "success";
+const FAIL = "fail";
+const BARRIER = "barrier";
+
 /**
- * @param {string} fileDir
+ * @typedef {number | null | SUCCESS | FAIL | BARRIER} Level
  */
-const createStructure = (fileDir) => {
-  const parentFileDir = joinPath(fileDir, "..");
-
-  const rawStructure = readRawStructure(fileDir);
-  const parentRawStructure = readRawStructure(parentFileDir);
-
-  const fileDirname = `${readArray(toSegments(fileDir), -1)}/`;
-  const theIndex = findLastIndex(parentRawStructure, (rawLayers) => {
-    return Boolean(
-      rawLayers.find((rawLayer) => {
-        if (typeof rawLayer === "string")
-          return `${rawLayer}/`.startsWith(fileDirname);
-        return `${rawLayer.name}/`.startsWith(fileDirname);
-      })
-    );
-  });
-
-  const structure = toStructure(rawStructure, fileDir);
-  const parentStructure = toStructure(parentRawStructure, parentFileDir);
 
-  for (let i = theIndex + 1; i <= parentRawStructure.length - 1; i++) {
-    structure.push(parentStructure[i]);
-  }
+/**
+ * @typedef {{
+ *  aliases: Record<string, string>,
+ *  exclude: string[],
+ *  include: string[],
+ *  excludeImports: string[],
+ * }} Options
+ */
 
-  return structure;
+/**
+ * @param {Options} options
+ * @param {string} contextFileSource
+ */
+const parseFileSource = (options, contextFileSource) => {
+  const fileSource = resolvePath(contextFileSource);
+  const parsedFileSource = parsePath(fileSource);
+  const fileDir = resolvePath(parsedFileSource.dir);
+  const filePath = resolvePath(fileDir, parsedFileSource.name);
+  const isIncludedFile = Boolean(
+    options.include.find((pattern) => minimatch(fileSource, pattern))
+  );
+  const isExcludedFile = Boolean(
+    options.exclude.find((pattern) => minimatch(fileSource, pattern))
+  );
+  return {
+    fileDir,
+    filePath,
+    isExcludedFile: !isIncludedFile || isExcludedFile,
+  };
 };
 
 /**
  * @param {string} cwd
+ * @param {string[]} excludeImports
  * @param {string} fileDir
  * @param {import('./2 layer').Aliases} aliases
  */
-const createModulePath = (cwd, fileDir, aliases) => {
+const createModulePath = (cwd, excludeImports, fileDir, aliases) => {
   /**
    * @param {string} moduleSourceWithAlias
    */
@@ -61,7 +69,28 @@ const createModulePath = (cwd, fileDir, aliases) => {
       aliases
     )(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 {import('./2 layer').Structure} structure
+ * @param {number} fileLevel
+ */
+const findLevelInCurrent = (structure, fileLevel) => {
+  /**
+   * @param {string} modulePath
+   */
+  return (modulePath) => {
+    const level = findLevel(structure)(modulePath);
+    if (level === null) return null;
+    return hasBarrier(structure, fileLevel)(level) ? BARRIER : level;
   };
 };
 
@@ -70,17 +99,86 @@ const createModulePath = (cwd, fileDir, aliases) => {
  */
 const findLevelInChild = (structure) => {
   /**
-   * @param {string} path
+   * @param {string} modulePath
    */
-  return (path) => {
-    const layer = findLayerWithSimilarPath(structure)(path);
+  return (modulePath) => {
+    const layer = findLayerWithReducedPath(structure)(modulePath);
     if (!layer) return null;
     const fileDir = layer.name;
     const rawChildStructure = readRawStructure(fileDir);
     const childStructure = toStructure(rawChildStructure, fileDir);
-    const childLevel = findLevel(childStructure)(path);
+    const childLevel = findLevel(childStructure)(modulePath);
     return childLevel !== null ? findLevel(structure)(fileDir) : null;
   };
 };
 
-module.exports = { createStructure, createModulePath, findLevelInChild };
+/**
+ * @param {string} cwd
+ * @param {string} fileDir
+ * @param {number} fileLevel
+ */
+const findLevelInParent = (cwd, fileDir, fileLevel) => {
+  const originalFileDir = fileDir;
+  const originalFileLevel = fileLevel;
+  /**
+   * @param {string} modulePath
+   */
+  return (modulePath) => {
+    const parentDir = resolvePath(originalFileDir, "..");
+    const parentDirs = reducedPaths(parentDir);
+    /**
+     * @param {[Level, string]} param
+     * @param {string} dir
+     */
+    const searchLevel = ([level, filePath], dir) => {
+      /**
+       * @param {Level} lv
+       * @return {[lv: Level, dir: string]}
+       */
+      const result = (lv) => [lv, dir];
+
+      if (level !== null) {
+        return result(level);
+      }
+
+      const structure = readStructure(dir);
+      if (structure.length === 0) {
+        return result(FAIL);
+      }
+
+      const fileLevel = findLevel(structure)(filePath);
+      const moduleLevel = findLevel(structure)(modulePath);
+
+      if (hasBarrier(structure, fileLevel)(moduleLevel)) {
+        return result(BARRIER);
+      } else if (fileLevel === null) {
+        return result(FAIL);
+      } else if (moduleLevel === null) {
+        return result(null);
+      } else {
+        return result(originalFileLevel + moduleLevel - fileLevel);
+      }
+    };
+
+    const [level] = parentDirs.reduce(searchLevel, [null, originalFileDir]);
+
+    if (
+      (level === null || level == FAIL) &&
+      isNotRegisteredNodeModule(cwd)(modulePath)
+    ) {
+      return SUCCESS;
+    }
+    return level === FAIL ? null : level;
+  };
+};
+
+module.exports = {
+  parseFileSource,
+  createModulePath,
+  findLevelInCurrent,
+  findLevelInChild,
+  findLevelInParent,
+  FAIL,
+  SUCCESS,
+  BARRIER,
+};