@slip-stream-kit/eslint-plugin 0.17.0 → 0.18.1

package/dist/index.js

@@ -1634,6 +1634,238 @@ var e2eTopLevelDescribe = {
   }
 };
 
+// src/utils/import-target.ts
+import path4 from "node:path";
+var DEFAULT_ROOT_ALIAS = "#root";
+var INDEX_FILE = /^index(?:\.[cm]?[jt]sx?)?$/;
+var literalValue = (source) => {
+  if (source === null || source === void 0) {
+    return null;
+  }
+  const value = source.type === "TSLiteralType" ? source.literal?.value : source.value;
+  return typeof value === "string" ? value : null;
+};
+var allSpecifiersAreTypes = (specifiers, key) => {
+  return specifiers !== void 0 && specifiers.length > 0 && specifiers.every((specifier) => {
+    return specifier[key] === "type";
+  });
+};
+var readImportSource = (node) => {
+  const candidate = node;
+  const sourceNode = candidate.type === "TSImportType" ? candidate.source ?? candidate.argument : candidate.source;
+  const specifier = literalValue(sourceNode);
+  if (specifier === null || sourceNode === null || sourceNode === void 0) {
+    return null;
+  }
+  const typeOnly = candidate.type === "TSImportType" || candidate.importKind === "type" || candidate.exportKind === "type" || allSpecifiersAreTypes(candidate.specifiers, candidate.type === "ImportDeclaration" ? "importKind" : "exportKind");
+  return { specifier, node: sourceNode, typeOnly };
+};
+var srcDirOf = (filename) => {
+  const packageRoot = findPackageRoot(filename);
+  if (packageRoot !== null) {
+    return filename.startsWith(`${packageRoot}/src/`) ? `${packageRoot}/src` : null;
+  }
+  const index = filename.lastIndexOf("/src/");
+  return index >= 0 ? filename.slice(0, index + "/src".length) : null;
+};
+var resolveUnderSrc = (filename, srcDir, specifier, rootAlias) => {
+  let absolute;
+  if (specifier === rootAlias || specifier.startsWith(`${rootAlias}/`)) {
+    absolute = path4.posix.join(srcDir, specifier.slice(rootAlias.length));
+  } else if (specifier.startsWith(".")) {
+    absolute = path4.posix.resolve(path4.posix.dirname(filename), specifier);
+  } else {
+    return null;
+  }
+  if (!absolute.startsWith(`${srcDir}/`)) {
+    return null;
+  }
+  return absolute.slice(srcDir.length + 1).split("/");
+};
+var fileDirsUnderSrc = (filename, srcDir) => {
+  return filename.slice(srcDir.length + 1).split("/").slice(0, -1);
+};
+var isFeaturePublicApi = (target) => {
+  return target.length === 2 || target.length === 3 && INDEX_FILE.test(target[2]);
+};
+var featureNameOf = (segments) => {
+  return segments[0] === "features" && segments.length >= 2 ? segments[1] : null;
+};
+var IMPORT_SELECTORS = [
+  "ImportDeclaration",
+  "ExportNamedDeclaration",
+  "ExportAllDeclaration",
+  "ImportExpression",
+  "TSImportType"
+];
+var UNLAYERED_TYPES = /* @__PURE__ */ new Set(["backend", "e2e"]);
+var isLayeredFile = (filename, ignore) => {
+  if (ignore.length > 0 && matchesAnyGlob(filename, ignore)) {
+    return false;
+  }
+  const packageRoot = findPackageRoot(filename);
+  return packageRoot === null || !UNLAYERED_TYPES.has(resolvePackageType(packageRoot));
+};
+
+// src/rules/feature-public-api/feature-public-api.ts
+var featurePublicApi = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require code outside a feature to import it only through its public API (`features/<name>` / its `index`), whatever the path form.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#feature-public-api"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          rootAlias: { type: "string", description: "The alias that maps to `src/` (default `#root`)." },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional globs; the rule is skipped for matching files."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      deepImport: "`{{specifier}}` reaches into the internals of feature `{{feature}}`. Import from its public API `{{publicApi}}` instead, exporting what you need from `features/{{feature}}/index.ts`."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const filename = context.filename.split("\\").join("/");
+    const srcDir = srcDirOf(filename);
+    if (srcDir === null || !isLayeredFile(filename, options.ignore ?? [])) {
+      return {};
+    }
+    const rootAlias = options.rootAlias ?? DEFAULT_ROOT_ALIAS;
+    const ownFeature = featureNameOf(fileDirsUnderSrc(filename, srcDir));
+    const check = (node) => {
+      const source = readImportSource(node);
+      const target = source === null ? null : resolveUnderSrc(filename, srcDir, source.specifier, rootAlias);
+      const feature = target === null ? null : featureNameOf(target);
+      if (source === null || feature === null || feature === ownFeature || isFeaturePublicApi(target)) {
+        return;
+      }
+      context.report({
+        node: source.node,
+        messageId: "deepImport",
+        data: { specifier: source.specifier, feature, publicApi: `${rootAlias}/features/${feature}` }
+      });
+    };
+    return Object.fromEntries(
+      IMPORT_SELECTORS.map((selector) => {
+        return [selector, check];
+      })
+    );
+  }
+};
+
+// src/rules/layer-imports/layer-imports.ts
+var TEST_FILE2 = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+var isTestFile = (filename) => {
+  return filename.includes("/__tests__/") || TEST_FILE2.test(filename);
+};
+var DEFAULT_LAYERS = [
+  ["lib", "components", "shared", "assets", "styles", "data"],
+  ["core", "entities"],
+  ["features"],
+  ["pages", "routes"],
+  ["app", "renderer", "mobile"]
+];
+var levelIndex = (layers) => {
+  return new Map(
+    layers.flatMap((level, index) => {
+      return level.map((layer) => {
+        return [layer, index];
+      });
+    })
+  );
+};
+var describeOrder = (layers) => {
+  return layers.map((level) => {
+    return level.join(", ");
+  }).join(" \u2192 ");
+};
+var layerImports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Allow imports only to the same or a lower layer of `src/` (lib/components \u2192 entities \u2192 features \u2192 pages/routes \u2192 app).",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#layer-imports"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          layers: {
+            type: "array",
+            items: { type: "array", items: { type: "string" }, minItems: 1 },
+            minItems: 1,
+            description: "Folders under `src/`, lowest level first; folders in one inner array share a level."
+          },
+          allowTypeImports: {
+            type: "boolean",
+            description: "Whether type-only imports may point at a higher layer (default true)."
+          },
+          rootAlias: { type: "string", description: "The alias that maps to `src/` (default `#root`)." },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional globs; the rule is skipped for matching files."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      upward: "`{{fromLayer}}` cannot import `{{specifier}}` from the higher layer `{{toLayer}}`. Layers import only their own level or below: {{order}}. Move the shared code down into a lower layer, or pass it in from above."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const filename = context.filename.split("\\").join("/");
+    const srcDir = srcDirOf(filename);
+    if (srcDir === null || isTestFile(filename) || !isLayeredFile(filename, options.ignore ?? [])) {
+      return {};
+    }
+    const layers = options.layers ?? DEFAULT_LAYERS;
+    const levels = levelIndex(layers);
+    const fromLayer = fileDirsUnderSrc(filename, srcDir)[0];
+    const fromLevel = fromLayer === void 0 ? void 0 : levels.get(fromLayer);
+    if (fromLayer === void 0 || fromLevel === void 0) {
+      return {};
+    }
+    const allowTypeImports = options.allowTypeImports ?? true;
+    const rootAlias = options.rootAlias ?? DEFAULT_ROOT_ALIAS;
+    const check = (node) => {
+      const source = readImportSource(node);
+      if (source === null || allowTypeImports && source.typeOnly) {
+        return;
+      }
+      const toLayer = resolveUnderSrc(filename, srcDir, source.specifier, rootAlias)?.[0];
+      const toLevel = toLayer === void 0 ? void 0 : levels.get(toLayer);
+      if (toLevel === void 0 || toLevel <= fromLevel) {
+        return;
+      }
+      context.report({
+        node: source.node,
+        messageId: "upward",
+        data: { fromLayer, toLayer, specifier: source.specifier, order: describeOrder(layers) }
+      });
+    };
+    return Object.fromEntries(
+      IMPORT_SELECTORS.map((selector) => {
+        return [selector, check];
+      })
+    );
+  }
+};
+
 // src/rules/max-components-per-file/max-components-per-file.ts
 var DEFAULT_MAX_COMPONENTS = 4;
 var ANONYMOUS_NAME2 = "component";
@@ -2122,6 +2354,72 @@ var maxJsxReturnSize = {
   }
 };
 
+// src/rules/no-feature-self-import/no-feature-self-import.ts
+var CONSUMER_DIRS = /* @__PURE__ */ new Set(["__tests__", "__stories__"]);
+var noFeatureSelfImport = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Forbid a feature from importing itself through its own public API, which closes an import cycle through `index.ts`.",
+      recommended: true,
+      url: "https://github.com/ArthurSaenz/infra-kit/tree/main/apps/infra-kit/eslint-plugin#no-feature-self-import"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          rootAlias: { type: "string", description: "The alias that maps to `src/` (default `#root`)." },
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional globs; the rule is skipped for matching files."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      selfImport: "`{{specifier}}` imports feature `{{feature}}` through its own public API from inside it, which makes an import cycle via `index.ts`. Import the module that defines it with a relative path instead.",
+      selfTypeImport: "`{{specifier}}` reads types of feature `{{feature}}` through its own public API from inside it. Import them from the module that defines them with a relative path; the public API is for code outside the feature."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const filename = context.filename.split("\\").join("/");
+    const srcDir = srcDirOf(filename);
+    if (srcDir === null || !isLayeredFile(filename, options.ignore ?? [])) {
+      return {};
+    }
+    const dirs = fileDirsUnderSrc(filename, srcDir);
+    const ownFeature = featureNameOf(dirs);
+    const isConsumer = dirs.some((dir) => {
+      return CONSUMER_DIRS.has(dir);
+    });
+    if (ownFeature === null || isConsumer) {
+      return {};
+    }
+    const rootAlias = options.rootAlias ?? DEFAULT_ROOT_ALIAS;
+    const check = (node) => {
+      const source = readImportSource(node);
+      const target = source === null ? null : resolveUnderSrc(filename, srcDir, source.specifier, rootAlias);
+      if (source === null || target === null || featureNameOf(target) !== ownFeature || !isFeaturePublicApi(target)) {
+        return;
+      }
+      context.report({
+        node: source.node,
+        // A type-only import is erased at build time, so it closes no runtime cycle.
+        messageId: source.typeOnly ? "selfTypeImport" : "selfImport",
+        data: { specifier: source.specifier, feature: ownFeature }
+      });
+    };
+    return Object.fromEntries(
+      IMPORT_SELECTORS.map((selector) => {
+        return [selector, check];
+      })
+    );
+  }
+};
+
 // src/rules/package-structure/package-structure.ts
 var DEFAULT_ENTRIES = {
   frontend: {
@@ -2607,10 +2905,10 @@ var propsTypeReference = {
 
 // src/rules/require-component-stories/require-component-stories.ts
 import { existsSync } from "node:fs";
-import path5 from "node:path";
+import path6 from "node:path";
 
 // src/utils/story-path.ts
-import path4 from "node:path";
+import path5 from "node:path";
 var DEFAULT_STORY_PATH_OPTIONS = {
   storiesDir: "__stories__",
   storySuffix: ".stories",
@@ -2629,10 +2927,10 @@ var parse = (filePath) => {
   const normalized = toPosix(filePath);
   const segments = normalized.split("/");
   const basename = segments[segments.length - 1] ?? "";
-  const ext = path4.posix.extname(basename);
+  const ext = path5.posix.extname(basename);
   const base = ext ? basename.slice(0, -ext.length) : basename;
   return {
-    dir: path4.posix.dirname(normalized),
+    dir: path5.posix.dirname(normalized),
     base,
     ext,
     parent: segments[segments.length - 2] ?? "",
@@ -2674,10 +2972,10 @@ var deriveExpectedStoryPaths = (filePath, opts) => {
     return [];
   }
   const parsed = parse(filePath);
-  const storyBaseDir = classification.mode === "feature-root" ? path4.posix.dirname(parsed.dir) : parsed.dir;
-  const storyDir = path4.posix.join(storyBaseDir, options.storiesDir);
+  const storyBaseDir = classification.mode === "feature-root" ? path5.posix.dirname(parsed.dir) : parsed.dir;
+  const storyDir = path5.posix.join(storyBaseDir, options.storiesDir);
   return options.storyExtensions.map((extension) => {
-    return path4.posix.join(storyDir, `${parsed.base}${options.storySuffix}${extension}`);
+    return path5.posix.join(storyDir, `${parsed.base}${options.storySuffix}${extension}`);
   });
 };
 
@@ -2797,7 +3095,7 @@ var requireComponentStories = {
           node: program,
           messageId: "missingStory",
           data: {
-            component: path5.posix.basename(context.filename.split("\\").join("/")),
+            component: path6.posix.basename(context.filename.split("\\").join("/")),
             expected: candidates[0] ?? ""
           }
         });
@@ -3083,7 +3381,7 @@ var requireJsdocExample = {
 };
 
 // src/rules/test-location/test-location.ts
-var TEST_FILE2 = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+var TEST_FILE3 = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 var SPEC_SUFFIX = /\.spec(\.[cm]?[jt]sx?)$/;
 var TESTS_DIR = "__tests__";
 var FEATURES_DIR = "features";
@@ -3116,7 +3414,7 @@ var locationViolation = (dirs, basename) => {
   };
 };
 var findViolations2 = (filename, ignore) => {
-  if (!TEST_FILE2.test(filename) || ignore.length > 0 && matchesAnyGlob(filename, ignore)) {
+  if (!TEST_FILE3.test(filename) || ignore.length > 0 && matchesAnyGlob(filename, ignore)) {
     return [];
   }
   const packageRoot = findPackageRoot(filename);
@@ -3191,6 +3489,9 @@ var rules = {
   "require-jsdoc-example": requireJsdocExample,
   "package-structure": packageStructure,
   "test-location": testLocation,
+  "layer-imports": layerImports,
+  "feature-public-api": featurePublicApi,
+  "no-feature-self-import": noFeatureSelfImport,
   "e2e-file-layout": e2eFileLayout,
   "e2e-file-order": e2eFileOrder,
   "e2e-page-object-member-order": e2ePageObjectMemberOrder,
@@ -3205,7 +3506,7 @@ var PLUGIN_NAME = "@wl";
 var plugin = {
   meta: {
     name: "@wl/eslint-plugin",
-    version: "0.17.0"
+    version: "0.18.1"
   },
   rules,
   configs: {}
@@ -3306,6 +3607,19 @@ plugin.configs.recommended = [
       [`${PLUGIN_NAME}/test-location`]: ["error", { ignore: ["**/*.e2e.test.*"] }]
     }
   },
+  // Import-path rules read where a specifier lands under `src/`, so they reach every source extension.
+  // They gate themselves on the package type (backend and e2e packages have no UI layering).
+  {
+    files: ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
+    plugins: {
+      [PLUGIN_NAME]: plugin
+    },
+    rules: {
+      [`${PLUGIN_NAME}/layer-imports`]: "error",
+      [`${PLUGIN_NAME}/feature-public-api`]: "error",
+      [`${PLUGIN_NAME}/no-feature-self-import`]: "error"
+    }
+  },
   // The e2e rules gate themselves on the package type, so a repo-wide glob costs one cached type
   // lookup per file elsewhere.
   {