eslint-plugin-stratified-design 0.4.0

package/.eslintrc.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  root: true,
+  extends: [
+    "eslint:recommended",
+    "plugin:eslint-plugin/recommended",
+    "plugin:node/recommended",
+  ],
+  env: {
+    node: true,
+  },
+  overrides: [
+    {
+      files: ["tests/**/*.js"],
+      env: { mocha: true },
+    },
+  ],
+};

package/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: release
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm test
+      - run: npm publish

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License (ISCL)
+
+Copyright (c) 2022 Hodoug Joung
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# eslint-plugin-stratified-design
+
+ESLint rules for stratified design, inspired by "[Grokking Simplicity](https://grokkingsimplicity.com)" written by Erick Normand, for practicing stratified design.
+
+## Installation
+
+First, ensure you have [ESLint](https://eslint.org/) installed:
+
+```sh
+npm i eslint --save-dev
+```
+
+Next, install `eslint-plugin-stratified-design`:
+
+```sh
+npm install eslint-plugin-stratified-design --save-dev
+```
+
+## Usage
+
+Add `stratified-design` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:
+
+```json
+{
+  "plugins": ["stratified-design"]
+}
+```
+
+Then configure the rules you wish to use under the rules section:
+
+```json
+{
+  "rules": {
+    "stratified-design/rule-name": ["error"]
+  }
+}
+```
+
+## 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.
+- [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

@@ -0,0 +1,182 @@
+# Require that lower-level modules be imported (lower-level-imports)
+
+This rule enforces the requirement for importing lower-level modules. Here's an explanation:
+
+- Functions in the same file within the same folder are considered to be at the same level.
+- Child folders are considered to be at a lower level than the parent folder.
+- Installed modules (node modules) are considered to be at the lowest level.
+
+However, you can modify this hierarchy using the `structure` option.
+
+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.
+
+### Options
+
+The syntax to specify the level structure is as follows:
+
+```json
+"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.
+
+To designate a layer as an interface layer, set `interface` to `true`:
+
+```json
+"lower-level-imports": ["error", {
+  "structure": ["layer1", { "name": "layer2", "interface": true }, "layer3"],
+}]
+```
+
+For the 'interface layer,' refer to "[Grokking Simplicity](https://grokkingsimplicity.com)."
+
+To locate a node module in the structure, set `isNodeModule` to `true`:
+
+```json
+"lower-level-imports": ["error", {
+  "structure": ["layer1", { "name": "nodeModule", "isNodeModule": 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"
+}]
+```
+
+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" }
+}]
+```
+
+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 }]
+```
+
+The options `structure` and `useLevelNumber` can be used together.
+
+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"] }]
+```
+
+The default is as follows:
+
+```json
+{
+  "include": ["**/*.{js,ts,jsx,tsx}"],
+  "exclude": ["**/*.{spec,test}.{js,ts,jsx,tsx}"]
+}
+```
+
+## Rule Details
+
+If a file structure is as follows:
+
+```
+src/
+ ┣ layer1.js
+ ┣ layer2/
+ ┃ ┣ file.js
+ ┃ ┣ otherFile.js
+ ┃ ┗ subFolder/
+ ┗ layer3/
+   ┣ entry.js
+   ┣ 1 layer.js
+   ┗ 2 layer.js
+```
+
+Examples of **incorrect** code for this rule:
+
+```js
+/* "lower-level-imports": ["error"] */
+// ./src/layer1.js
+import { func } from "../layer2/file";
+```
+
+```js
+/* "lower-level-imports": ["error"] */
+// ./src/layer2/file.js
+import { func } from "./otherFile";
+```
+
+```js
+/* "lower-level-imports": ["error", { "structure": ["layer1", "layer2"] }] */
+// ./src/layer2/file.js
+import { func } from "../layer1";
+```
+
+```js
+/* "lower-level-imports": ["error", {
+  "structure": ["layer1", { name: "layer2", interface: true }, "layer3"]
+}] */
+// ./src/layer1.js
+import { func } from "../layer3/entry";
+```
+
+```js
+/* "lower-level-imports": ["error", {
+  "structure":  ["layer1", { "name": "nodeModule", "isNodeModule": true }, "layer3"],
+}] */
+// ./src/layer3/entry.js
+import { func } from "nodeModule";
+```
+
+```js
+/* "lower-level-imports": ["error", { "useLevelNumber": true }}] */
+// ./src/layer1.js
+import { func } from "layer3/1 layer";
+```
+
+Examples of **correct** code for this rule:
+
+```js
+/* "lower-level-imports": ["error"] */
+// ./src/layer2/file.js
+import { func } from "./subFolder/file";
+```
+
+```js
+/* "lower-level-imports": ["error", { "structure": ["layer1", "layer2"] }] */
+// ./src/layer1.js
+import { func } from "../layer2/file";
+```
+
+```js
+/* "lower-level-imports": ["error", {
+  "structure": ["layer1", "layer2"],
+  "alias": { "@/": "./src/" }
+}] */
+// ./src/layer1.js
+import { func } from "@/layer2/file";
+```
+
+```js
+/* "lower-level-imports": ["error", { "useLevelNumber": true }] */
+// ./src/layer3/1 layer.js
+import { func } from "./2 layer";
+```
+
+```js
+/* "lower-level-imports": ["error", { "useLevelNumber": true }] */
+// ./src/layer3/entry.js
+import { func } from "./1 layer";
+```
+
+```js
+/* "lower-level-imports": ["error", { "structure": ["layer1", "layer3"], "useLevelNumber": true }] */
+// ./src/layer.js
+import { func } from "../layer3/entry";
+```

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

@@ -0,0 +1,30 @@
+# Disallow calling functions in the same file (no-same-level-funcs)
+
+This rule prohibits calling functions at the same level in the same file.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+function func1(...) {
+  ...
+}
+
+const func2(...) => { ... }
+
+function func3(...) {
+  func1(...);
+  func2(...);
+}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+function func1(...) {
+  const func2(...) => { ... };
+  ...
+  func2(...);
+}
+```

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

@@ -0,0 +1,220 @@
+const { minimatch } = require("minimatch");
+const { report: reportError } = require("./2 layer");
+const {
+  isNodeModule,
+  findLevel: findLayerLevel,
+  hasInterface: hasInterfaceBetween,
+  removeAlias: removeAliasFromModuleSource,
+} = require("./3 layer");
+const {
+  toRelative,
+  toSegments,
+  toPath,
+  resolvePath,
+  parsePath,
+} = require("./4 layer");
+
+const FINISHED = "finished";
+
+/**
+ *
+ * @param {string} cwd
+ * @param {*} options
+ * @returns
+ */
+const createRootDir = (cwd, options) => {
+  return resolvePath(cwd, options.root);
+};
+
+/**
+ * @param {*} 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 = options.include.find((pattern) =>
+    minimatch(fileSource, pattern)
+  );
+  const isExcludedFile = options.exclude.find((pattern) =>
+    minimatch(fileSource, pattern)
+  );
+  return {
+    fileDir,
+    filePath,
+    isExcludedFile: !isIncludedFile || isExcludedFile,
+  };
+};
+
+/**
+ * @param {string} cwd
+ * @param {string} fileDir
+ * @param {{alias: string, path: string}[]} aliases
+ */
+const createModulePath = (cwd, fileDir, aliases) => {
+  const removeAlias = removeAliasFromModuleSource(cwd, fileDir, aliases);
+  /**
+   * @param {string} moduleSourceWithAlias
+   */
+  return (moduleSourceWithAlias) => {
+    const moduleSource = removeAlias(moduleSourceWithAlias);
+    const isNodeModule = moduleSource.startsWith(".") === false;
+    return isNodeModule ? moduleSource : resolvePath(fileDir, moduleSource);
+  };
+};
+
+/**
+ * Report error about using `options.useLevelNumber`
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {*} options
+ * @param {string} rootDir
+ * @param {string} filePath
+ */
+const reportHasProperLevelNumber = (context, options, rootDir, filePath) => {
+  /**
+   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {string} modulePath
+   */
+  return (node, modulePath) => {
+    if (!options.useLevelNumber) return;
+
+    const report = (messageId) =>
+      reportError(context, rootDir, filePath)(node, messageId, modulePath);
+
+    const extractLevel = (segment) => {
+      const level = segment.split(" ")[0];
+      return /^[\d]+$/.test(level) ? Number(level) : null;
+    };
+
+    const parentPath = (() => {
+      const moduleSegment = toSegments(modulePath);
+      const fileSegment = toSegments(filePath);
+      const parent = moduleSegment.reduce((parent, seg, index) => {
+        if (fileSegment[index] === seg) parent.push(seg);
+        return parent;
+      }, []);
+      return toPath(parent);
+    })();
+
+    const { moduleLevel, isInterfaceError } = (() => {
+      const segments = toSegments(toRelative(parentPath, modulePath));
+      const level = extractLevel(segments[1]);
+      return {
+        moduleLevel: level,
+        isInterfaceError: segments.length > 2,
+      };
+    })();
+
+    if (isInterfaceError) {
+      report("interface");
+      return FINISHED;
+    }
+
+    if (moduleLevel === null) return;
+
+    const fileLevel = (() => {
+      const segments = toSegments(toRelative(parentPath, filePath));
+      const level = extractLevel(segments[1]);
+      if (level === null && segments.length === 2 && segments[0] == ".")
+        return -1;
+      return level;
+    })();
+
+    if (fileLevel === null) {
+      report("interface");
+      return FINISHED;
+    }
+
+    if (fileLevel >= moduleLevel) {
+      report("not-lower-level");
+      return FINISHED;
+    }
+
+    return FINISHED;
+  };
+};
+
+/**
+ * @param {string} fileDir
+ * @return return `FINISHED` if the imported module(`modulePath`) is in a sub directory of the file directory(`fileDir`)
+ */
+const reportInSubDirOfFileDir = (fileDir) => {
+  /**
+   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {string} modulePath
+   */
+  return (node, modulePath) => {
+    const relModulePath = toRelative(fileDir, modulePath);
+    if (
+      relModulePath.startsWith("..") === false &&
+      toSegments(relModulePath).length >= 3
+    ) {
+      return FINISHED;
+    }
+  };
+};
+
+/**
+ * Report error about using `options.structure`
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {{[string]: string | {name: string, isNodeModule: boolean, interface: boolean}}} structure
+ * @param {string} rootDir
+ * @param {number | null} fileLevel
+ * @param {string} filePath
+ */
+const reportHasProperLevel = (
+  context,
+  structure,
+  rootDir,
+  fileLevel,
+  filePath
+) => {
+  const findLevel = findLayerLevel(structure);
+  const hasInterface = hasInterfaceBetween(structure, fileLevel);
+
+  /**
+   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {string} modulePath
+   */
+  return (node, modulePath) => {
+    const report = (messageId) =>
+      reportError(context, rootDir, filePath)(node, messageId, modulePath);
+
+    const isNodeModulePath = isNodeModule(rootDir)(modulePath);
+
+    if (fileLevel === null) {
+      if (!isNodeModulePath) report("not-registered:file");
+      return FINISHED;
+    }
+
+    const moduleLevel = findLevel(modulePath);
+    if (moduleLevel === null) {
+      if (!isNodeModulePath) report("not-registered:module");
+      return FINISHED;
+    }
+
+    if (fileLevel >= moduleLevel) {
+      report("not-lower-level");
+      return FINISHED;
+    }
+
+    if (hasInterface(moduleLevel)) {
+      report("interface");
+      return FINISHED;
+    }
+
+    return FINISHED;
+  };
+};
+
+module.exports = {
+  FINISHED,
+  createRootDir,
+  parseFileSource,
+  createModulePath,
+  reportHasProperLevelNumber,
+  reportInSubDirOfFileDir,
+  reportHasProperLevel,
+};

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

@@ -0,0 +1,25 @@
+const { isNodeModule } = require("./3 layer");
+const { toRelative } = require("./4 layer");
+
+/**
+ * Report eslint error
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {string} rootDir
+ * * @param {string} filePath
+ */
+const report = (context, rootDir, filePath) => {
+  /**
+   * @param {import('eslint').Rule.NodeParentExtension} node
+   * @param {string} messageId
+   * @param {string} modulePath
+   */
+  return (node, messageId, modulePath) => {
+    const module = isNodeModule(rootDir)(modulePath)
+      ? modulePath
+      : toRelative(rootDir, modulePath);
+    const file = toRelative(rootDir, filePath);
+    context.report({ node, messageId, data: { module, file } });
+  };
+};
+
+module.exports = { report };

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

@@ -0,0 +1,108 @@
+const {
+  toSegments,
+  toPath,
+  joinPath,
+  resolvePath,
+  toRelative,
+} = require("./4 layer");
+
+/**
+ * @param {*} options
+ * @param {string} rootDir
+ */
+const createStructure = (options, rootDir) => {
+  return options.structure.map((layer) => {
+    const theLayer = typeof layer === "string" ? { name: layer } : layer;
+    return theLayer.isNodeModule
+      ? theLayer
+      : { ...theLayer, name: joinPath(rootDir, theLayer.name) };
+  });
+};
+
+/**
+ * @param {*} options
+ */
+const createAliases = (options) => {
+  return Object.keys(options.aliases)
+    .sort((a, b) => b.length - a.length)
+    .map((alias) => ({ alias, path: options.aliases[alias] }));
+};
+
+/**
+ * Replace an alias into the corresponding path
+ * @param {string} cwd
+ * @param {string} fileDir
+ * @param {{alias: string, path: string}[]} aliases
+ */
+const removeAlias = (cwd, fileDir, aliases) => {
+  /**
+   * @param {string} moduleSource
+   */
+  return (moduleSource) => {
+    const { alias, path } =
+      aliases.find(({ alias }) => moduleSource.startsWith(alias)) || {};
+    if (!alias) return moduleSource;
+    const modulePath = resolvePath(cwd, moduleSource.replace(alias, path));
+    return toRelative(fileDir, modulePath);
+  };
+};
+
+/**
+ * Check if a module is node module
+ * @param {string} rootDir
+ * @returns `true` if `modulePath` is node module path
+ */
+const isNodeModule = (rootDir) => {
+  /**
+   * @param {string} modulePath
+   */
+  return (modulePath) => {
+    return modulePath.startsWith(rootDir) === false;
+  };
+};
+
+/**
+ * Find the layer level for a module
+ * @param {{[string]: string | {name: string, isNodeModule: boolean, interface: boolean}}} structure
+ * @returns the level of the module with `path`
+ */
+const findLevel = (structure) => {
+  /**
+   * @param {string} path
+   */
+  return (path) => {
+    const segments = toSegments(path);
+    const level = segments.reduce((level, _, index) => {
+      if (level >= 0) return level;
+      const path = toPath(segments.slice(0, segments.length - index));
+      return structure.findIndex((layer) => layer.name === path);
+    }, -1);
+    return level >= 0 ? level : null;
+  };
+};
+
+/**
+ * Check if there is an interface between file layer and module layer
+ * @param {{[string]: string | {name: string, isNodeModule: boolean, interface: boolean}}} structure
+ * @param {number} fileLevel
+ */
+const hasInterface = (structure, fileLevel) => {
+  /**
+   * @param {number} moduleLevel
+   */
+  return (moduleLevel) => {
+    const layerInterface = structure
+      .slice(fileLevel + 1, moduleLevel)
+      .find((layer) => layer.interface);
+    return Boolean(layerInterface);
+  };
+};
+
+module.exports = {
+  isNodeModule,
+  findLevel,
+  hasInterface,
+  createStructure,
+  createAliases,
+  removeAlias,
+};