@kekkai/structure-lint 1.0.0 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ In medium to large front-end projects, folder structures tend to degrade over ti
 - Architecture rules live only in documentation, not in tooling
 - Documentation and actual code gradually drift apart
 
-@kekkai/structure-lint is not about code style.  
+`@kekkai/structure-lint` is not about code style.  
 Its goal is to **turn folder structure and dependency direction into enforceable ESLint rules**.
 
 > ⚠️ **ESLint v9+ Required**
@@ -61,10 +61,6 @@ This package is built on three core ideas:
 
 ```bash
 npm install -D @kekkai/structure-lint
-# or
-pnpm add -D @kekkai/structure-lint
-# or
-yarn add -D @kekkai/structure-lint
 ```
 
 This package provides:
@@ -145,6 +141,26 @@ This file is read by both:
    */
   "lintFiles": "src/{folder}/**/*.{ts,tsx}",
 
+  /**
+   * moduleLayout
+   *   type (optional)
+   *   - 'folder' | 'flat'
+   *
+   * Controls how modules are structured within each layer and how
+   * relative import restrictions are generated.
+   *
+   * - 'folder' (default):
+   *   Each module lives in its own subfolder (e.g. components/Card/*),
+   *   and imports are only allowed via the module entry.
+   *
+   * - 'flat':
+   *   Modules are represented directly by files under the layer
+   *   (e.g. components/Card.tsx).
+   *
+   * Default: 'folder'
+   */
+  "moduleLayout": "folder",
+
   /**
    * dependencyFlow
    *   type (required):
@@ -248,6 +264,52 @@ Based on the `markerTag` configuration, the CLI will locate and overwrite the fo
 <!-- DEPENDENCY_RULE:END -->
 ```
 
+## 🔁 Circular Dependencies (Optional)
+
+`@kekkai/structure-lint` enforces one-way dependency flow **across layers**,
+but intentionally allows **same-layer imports as a design trade-off**.
+
+As a result, circular dependencies may still occur within the same layer.
+This is usually acceptable for small modules, but may become risky as the codebase grows.
+
+If your team wants to detect these cases, you can optionally enable:
+
+- `import/no-cycle` (from [`eslint-plugin-import`](https://www.npmjs.com/package/eslint-plugin-import))
+
+> ⚠️ **TypeScript projects must configure a resolver**, otherwise circular dependencies may not be detected.
+> Try [`eslint-import-resolver-typescript`](https://www.npmjs.com/package/eslint-import-resolver-typescript).
+
+```ts
+import imports from 'eslint-plugin-import';
+import { defineConfig } from 'eslint/config';
+import { createStructureLint } from '@kekkai/structure-lint';
+
+export default defineConfig([
+  {
+    plugins: {
+      import: imports,
+    },
+    settings: {
+      'import/parsers': {
+        // Project file extensions handled by the TypeScript parser
+        '@typescript-eslint/parser': ['.ts', '.tsx'],
+      },
+      'import/resolver': {
+        typescript: true,
+        node: {
+          // Project file extensions used for module resolution
+          extensions: ['.ts', '.tsx'],
+        },
+      },
+    },
+    rules: {
+      'import/no-cycle': 'error',
+    },
+  },
+  ...createStructureLint(),
+]);
+```
+
 ## 🧠 Philosophy
 
 `@kekkai/structure-lint` treats folder structure as architecture.

package/README.zh-TW.md

@@ -60,10 +60,6 @@
 
 ```bash
 npm install -D @kekkai/structure-lint
-# or
-pnpm add -D @kekkai/structure-lint
-# or
-yarn add -D @kekkai/structure-lint
 ```
 
 本套件同時提供：
@@ -140,6 +136,27 @@ structure.config.json 用來定義專案的 資料夾依賴規則 與 文件同
    */
   "lintFiles": "src/{folder}/**/*.{ts,tsx}",
 
+  /**
+   * moduleLayout
+   *   type (optional)
+   *   - 'folder' | 'flat'
+   *
+   * 用來指定各層（layer）中模組的組織方式，
+   * 並影響相對路徑（relative import）的限制規則產生方式。
+   *
+   * - 'folder'（預設）：
+   *   每個模組以資料夾為單位存在
+   *   （例如 components/Card/*），
+   *   跨模組只能透過模組入口（index.ts）引用。
+   *
+   * - 'flat'：
+   *   模組直接以檔案形式存在於該層底下
+   *   （例如 components/Card.tsx）。
+   *
+   * 預設值：'folder'
+   */
+  "moduleLayout": "folder",
+
   /**
    * dependencyFlow
    *   type (required):
@@ -238,6 +255,51 @@ flowchart TD
 <!-- DEPENDENCY_RULE:END -->
 ```
 
+## 🔁 Circular Dependencies (Optional)
+
+`@kekkai/structure-lint` 會嚴格限制 **跨層** 的單向依賴方向，但仍刻意允許 **同一層內的模組彼此引用** 作為設計取捨。
+
+因此，在相同 layer 之內，仍然可能發生循環依賴（circular dependencies）。
+這在模組規模較小時通常是可接受的，但隨著專案成長，可能會逐漸帶來風險。
+
+如果你的團隊希望進一步偵測這類情況，可以選擇性地啟用以下規則：
+
+- `import/no-cycle` (from [`eslint-plugin-import`](https://www.npmjs.com/package/eslint-plugin-import))
+
+> ⚠️ **TypeScript 專案必須正確設定 resolver**，否則可能無法偵測到循環依賴。
+> 建議搭配使用 [`eslint-import-resolver-typescript`](https://www.npmjs.com/package/eslint-import-resolver-typescript)。
+
+```ts
+import imports from 'eslint-plugin-import';
+import { defineConfig } from 'eslint/config';
+import { createStructureLint } from '@kekkai/structure-lint';
+
+export default defineConfig([
+  {
+    plugins: {
+      import: imports,
+    },
+    settings: {
+      'import/parsers': {
+        // Project file extensions handled by the TypeScript parser
+        '@typescript-eslint/parser': ['.ts', '.tsx'],
+      },
+      'import/resolver': {
+        typescript: true,
+        node: {
+          // Project file extensions used for module resolution
+          extensions: ['.ts', '.tsx'],
+        },
+      },
+    },
+    rules: {
+      'import/no-cycle': 'error',
+    },
+  },
+  ...createStructureLint(),
+]);
+```
+
 ## 🧠 Philosophy
 
 `@kekkai/structure-lint` 將資料夾結構視為架構本身。

package/dist/bin.js

@@ -77,7 +77,7 @@ function loadStructureConfig(defaultConfigPath = "structure.config.json") {
 	if (!fs.existsSync(configPath)) throw new Error(`structure.config.json not found at ${configPath}`);
 	return isConfigValid(JSON.parse(fs.readFileSync(configPath, "utf-8")));
 }
-function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRules, packageImportRules }) {
+function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, moduleLayout, overrideRules, packageImportRules }) {
 	if (typeof appAlias !== "string" || !appAlias?.trim()) throw new Error("appAlias is required in structure.config.json");
 	if (!Array.isArray(dependencyFlow)) throw new Error("dependencyFlow must be an array in structure.config.json");
 	else for (const item of dependencyFlow) if (!Array.isArray(item)) throw new Error("Each item in dependencyFlow must be a tuple [string, string, options?] in structure.config.json");
@@ -90,6 +90,11 @@ function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRule
 		else if (typeof markerTag !== "string" || !markerTag?.trim()) throw new Error("docs.markerTag is required in structure.config.json if docs is provided");
 		else if (content && typeof content !== "string") throw new Error("docs.content must be a string in structure.config.json");
 	}
+	const files = Array.isArray(lintFiles) ? lintFiles : [lintFiles];
+	if (!files.length) throw new Error("lintFiles is required in structure.config.json");
+	else for (const file of files) if (typeof file !== "string" || !file?.trim()) throw new Error("lintFiles must be a non-empty string or an array of non-empty strings in structure.config.json");
+	else if (!LINT_FILES_REGEX.test(file)) throw new Error("Each lintFiles entry must include the \"{folder}\" placeholder in structure.config.json");
+	if (moduleLayout !== void 0 && !["folder", "flat"].includes(moduleLayout)) throw new Error("moduleLayout must be either \"folder\" or \"flat\" in structure.config.json");
 	if (overrideRules) {
 		const entries = Object.entries(overrideRules);
 		if (entries.some(([key]) => !folders.includes(key))) throw new Error("overrideRules contains invalid folder keys not present in dependencyFlow in structure.config.json");
@@ -105,15 +110,12 @@ function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRule
 			else if (allowedInFolders.some((folder) => !folders.includes(folder))) throw new Error("allowedInFolders in packageImportRule contains invalid folder names not present in dependencyFlow in structure.config.json");
 		}
 	}
-	const files = Array.isArray(lintFiles) ? lintFiles : [lintFiles];
-	if (!files.length) throw new Error("lintFiles is required in structure.config.json");
-	else for (const file of files) if (typeof file !== "string" || !file?.trim()) throw new Error("lintFiles must be a non-empty string or an array of non-empty strings in structure.config.json");
-	else if (!LINT_FILES_REGEX.test(file)) throw new Error("Each lintFiles entry must include the \"{folder}\" placeholder in structure.config.json");
 	return {
 		appAlias,
 		dependencyFlow,
 		docs,
 		lintFiles: files,
+		moduleLayout,
 		overrideRules,
 		packageImportRules
 	};

package/dist/index.js

@@ -25,7 +25,7 @@ function loadStructureConfig(defaultConfigPath = "structure.config.json") {
 	if (!fs.existsSync(configPath)) throw new Error(`structure.config.json not found at ${configPath}`);
 	return isConfigValid(JSON.parse(fs.readFileSync(configPath, "utf-8")));
 }
-function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRules, packageImportRules }) {
+function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, moduleLayout, overrideRules, packageImportRules }) {
 	if (typeof appAlias !== "string" || !appAlias?.trim()) throw new Error("appAlias is required in structure.config.json");
 	if (!Array.isArray(dependencyFlow)) throw new Error("dependencyFlow must be an array in structure.config.json");
 	else for (const item of dependencyFlow) if (!Array.isArray(item)) throw new Error("Each item in dependencyFlow must be a tuple [string, string, options?] in structure.config.json");
@@ -38,6 +38,11 @@ function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRule
 		else if (typeof markerTag !== "string" || !markerTag?.trim()) throw new Error("docs.markerTag is required in structure.config.json if docs is provided");
 		else if (content && typeof content !== "string") throw new Error("docs.content must be a string in structure.config.json");
 	}
+	const files = Array.isArray(lintFiles) ? lintFiles : [lintFiles];
+	if (!files.length) throw new Error("lintFiles is required in structure.config.json");
+	else for (const file of files) if (typeof file !== "string" || !file?.trim()) throw new Error("lintFiles must be a non-empty string or an array of non-empty strings in structure.config.json");
+	else if (!LINT_FILES_REGEX.test(file)) throw new Error("Each lintFiles entry must include the \"{folder}\" placeholder in structure.config.json");
+	if (moduleLayout !== void 0 && !["folder", "flat"].includes(moduleLayout)) throw new Error("moduleLayout must be either \"folder\" or \"flat\" in structure.config.json");
 	if (overrideRules) {
 		const entries = Object.entries(overrideRules);
 		if (entries.some(([key]) => !folders.includes(key))) throw new Error("overrideRules contains invalid folder keys not present in dependencyFlow in structure.config.json");
@@ -53,15 +58,12 @@ function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRule
 			else if (allowedInFolders.some((folder) => !folders.includes(folder))) throw new Error("allowedInFolders in packageImportRule contains invalid folder names not present in dependencyFlow in structure.config.json");
 		}
 	}
-	const files = Array.isArray(lintFiles) ? lintFiles : [lintFiles];
-	if (!files.length) throw new Error("lintFiles is required in structure.config.json");
-	else for (const file of files) if (typeof file !== "string" || !file?.trim()) throw new Error("lintFiles must be a non-empty string or an array of non-empty strings in structure.config.json");
-	else if (!LINT_FILES_REGEX.test(file)) throw new Error("Each lintFiles entry must include the \"{folder}\" placeholder in structure.config.json");
 	return {
 		appAlias,
 		dependencyFlow,
 		docs,
 		lintFiles: files,
+		moduleLayout,
 		overrideRules,
 		packageImportRules
 	};
@@ -69,7 +71,8 @@ function isConfigValid({ appAlias, dependencyFlow, docs, lintFiles, overrideRule
 
 //#endregion
 //#region src/lint/main.ts
-function createStructureLint({ appAlias, dependencyFlow, lintFiles, overrideRules, packageImportRules } = loadStructureConfig()) {
+function createStructureLint(config) {
+	const { appAlias, dependencyFlow, lintFiles, moduleLayout = "folder", overrideRules, packageImportRules } = config || loadStructureConfig();
 	const folders = extractAllFolders(dependencyFlow);
 	return folders.map((folder) => {
 		const disableFolderImports = getDisableFolderImports(dependencyFlow, folders, folder);
@@ -81,7 +84,11 @@ function createStructureLint({ appAlias, dependencyFlow, lintFiles, overrideRule
 				"no-restricted-imports": ["error", {
 					patterns: [
 						{
-							group: ["../*/**"],
+							group: ["./../**", "././**"],
+							message: "🚫 Redundant relative path segments (././, ./../) are not allowed. They bypass structural import rules."
+						},
+						{
+							group: [moduleLayout === "folder" ? "../*/**" : "../**"],
 							message: "\n🚫 Do not import from upper-level directories. Use the project alias (e.g. \"~app/*\") to follow the dependency flow."
 						},
 						{

package/dist/main.d.ts

@@ -1,3 +1,3 @@
 import type { ConfigWithExtendsArray } from '@eslint/config-helpers';
 import type { DefineOptions } from './types';
-export declare function createStructureLint<F extends string>({ appAlias, dependencyFlow, lintFiles, overrideRules, packageImportRules, }?: Omit<DefineOptions<F>, 'docs'>): ConfigWithExtendsArray;
+export declare function createStructureLint<F extends string>(config?: Omit<DefineOptions<F>, 'docs'>): ConfigWithExtendsArray;

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export interface DefineOptions<F extends string> {
     dependencyFlow: DependencyFlow<F>[];
     docs?: DocsOptions;
     lintFiles: string | string[];
+    moduleLayout?: 'folder' | 'flat';
     overrideRules?: Partial<Record<F, Partial<RulesConfig>>>;
     packageImportRules?: PackageImportRule<F>[];
 }

package/dist/utils.d.ts

@@ -4,4 +4,4 @@ export declare function extractAllFolders<F extends string>(dependencyFlow: Depe
 export declare function getDisableFolderImports<F extends string>(config: DependencyFlow<F>[], folders: Readonly<F[]>, folder: F): F[];
 export declare function getLintFiles<F extends string>(folder: F, lintFiles: string | string[]): string[];
 export declare function loadStructureConfig<F extends string>(defaultConfigPath?: string): DefineOptions<F>;
-export declare function isConfigValid<F extends string>({ appAlias, dependencyFlow, docs, lintFiles, overrideRules, packageImportRules, }: Partial<Record<keyof DefineOptions<F>, JsonValue>>): DefineOptions<F>;
+export declare function isConfigValid<F extends string>({ appAlias, dependencyFlow, docs, lintFiles, moduleLayout, overrideRules, packageImportRules, }: Partial<Record<keyof DefineOptions<F>, JsonValue>>): DefineOptions<F>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kekkai/structure-lint",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "Config-driven ESLint structure rule generator enforcing one-way folder dependency flow, with a separate CLI for docs sync/verification.",
   "type": "module",