@kekkai/structure-lint 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taco Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+**English** | [繁體中文](https://github.com/taco3064/kekkai-structure-lint/blob/main/README.zh-TW.md)
+
+# 📦 @kekkai/structure-lint
+
+A **config-driven** ESLint structure rule generator that enforces **one-way folder dependency flow** in your project, with a separate CLI for syncing and validating dependency rules in documentation.
+
+## 🔍 What Problem Does This Solve?
+
+In medium to large front-end projects, folder structures tend to degrade over time:
+
+- Modules can freely import each other without clear boundaries
+- Relative imports (`../`) make dependency relationships hard to reason about
+- Architecture rules live only in documentation, not in tooling
+- Documentation and actual code gradually drift apart
+
+@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**
+>
+> This package is built for **ESLint Flat Config**  
+> and requires **ESLint v9 or later**.
+>
+> If your project is still using legacy `.eslintrc`,
+> please migrate to Flat Config before using this package.
+
+## ✨ Core Ideas
+
+This package is built on three core ideas:
+
+1. **Folder-as-a-Module**
+   - Treat each subfolder as a standalone module (e.g. `hooks/useShuffleCards`, `components/Card`)
+   - Prefer `index.ts` as the module entry to keep imports consistent and readable
+
+2. **One-way Dependency Flow**
+   - Dependency rules are defined at the folder level: each folder may only depend on allowed downstream folders
+   - No reverse dependencies and no layer-skipping shortcuts
+
+3. **Enforceable Imports (Alias-only Cross-folder Imports)**
+   - Relative imports (`./`) are allowed within a module
+   - Cross-folder imports must use the project alias (e.g. `~app/...`) to prevent uncontrolled `../` shortcut dependencies
+
+> 🗂️ **Example Folder Structure:**
+>
+> ```text
+> src/
+> ├─ components/
+> │  └─ Card/
+> │     ├─ Component.tsx
+> │     ├─ index.ts
+> │     └─ types.ts
+> ├─ containers/
+> │  └─ DeckDrawStage/
+> │     ├─ Container.tsx
+> │     ├─ index.ts
+> │     └─ types.ts
+> └─ main.tsx
+> ```
+
+## 📥 Installation
+
+```bash
+npm install -D @kekkai/structure-lint
+# or
+pnpm add -D @kekkai/structure-lint
+# or
+yarn add -D @kekkai/structure-lint
+```
+
+This package provides:
+
+- An ESLint Flat Config generator
+- A standalone CLI for documentation sync and validation
+
+## 🚀 Quick Start
+
+- **eslint.config.(js|ts)**
+  `@kekkai/structure-lint` supports two usage patterns.
+  Choose the one that best fits your project needs:
+
+  ```ts
+  import { defineConfig } from 'eslint/config';
+  import { createStructureLint } from '@kekkai/structure-lint';
+
+  export default defineConfig([
+    // Options 1. Use structure.config.json
+    ...structure.defineConfig(),
+
+    // Options 2. Define rules directly in eslint.config.ts
+    ...structure.defineConfig({
+      appAlias: '~app',
+      lintFiles: 'src/{folder}/**/*.{ts,tsx}',
+      dependencyFlow: [
+        ['pages', 'layouts'],
+        ['layouts', 'containers'],
+        ['containers', 'components'],
+        ['components', 'hooks'],
+      ],
+    }),
+  ]);
+  ```
+
+- **CLI**
+  `@kekkai/structure-lint` provides a standalone CLI to **sync Dependency Flow rules into a specified Markdown file**.
+
+  ```bash
+  npx structure-lint
+  ```
+
+  > 💡 The CLI reads **only** `structure.config.json`.
+
+## 🧩 structure.config.json
+
+`structure.config.json` is used to define folder dependency rules and documentation sync settings for the project.
+This file is read by both:
+
+- ESLint configuration (createStructureLint())
+- CLI (npx structure-lint)
+
+### 🔧 Configuration Options
+
+```ts
+{
+  /**
+   * appAlias
+   *   type (required):
+   *   - string
+   *
+   * The module alias used in the project to enforce a unified import path
+   * for cross-folder dependencies.
+   * - All cross-folder imports MUST use this alias
+   * - Replaces unsafe and hard-to-track `../` relative imports
+   */
+  "appAlias": "~app",
+
+  /**
+   * lintFiles
+   *   type (required):
+   *   - string | string[]
+   *
+   * Specifies the file paths where ESLint structure rules should be applied.
+   * - Must include the `{folder}` placeholder
+   * - `{folder}` will be replaced at runtime with each folder name
+   *   defined in `dependencyFlow`
+   */
+  "lintFiles": "src/{folder}/**/*.{ts,tsx}",
+
+  /**
+   * dependencyFlow
+   *   type (required):
+   *   - [
+   *       string, // from folder
+   *       string, // to folder
+   *       {
+   *         description?: string; // Used only for documentation output
+   *                               // (Mermaid flowchart annotation),
+   *                               // does NOT affect ESLint rules
+   *         selfOnly?: boolean;   // When true, the from folder may only
+   *                               // directly depend on the to folder,
+   *                               // with no further downstream extension
+   *       }?
+   *     ][]
+   *
+   * Defines one-way dependency relationships between folders.
+   */
+  "dependencyFlow": [
+    ["pages", "containers"],
+    ["containers", "contexts", { description: "Only Provider" }],
+    ["containers", "components"],
+    ["components", "hooks"],
+    ["hooks", "contexts", { description: "Only Context", selfOnly: true }]
+  ],
+
+  /**
+   * docs
+   *   type (optional)
+   *   - {
+   *       file: string;      // Target Markdown file path
+   *       markerTag: string; // Identifier used to locate the auto-generated block
+   *       content?: string;  // Custom documentation content
+   *     }
+   *
+   * Configures the CLI to sync `dependencyFlow` into a Markdown file.
+   */
+  "docs": {
+    "file": "README.md",
+    "markerTag": "DEPENDENCY_RULE"
+  },
+
+  /**
+   * overrideRules
+   *   type (optional)
+   *   - {
+   *       [key: string]:       // Key must be a folder name defined in dependencyFlow
+   *         EslintRulesConfig; // ESLint rules configuration object
+   *     }
+   *
+   * Overrides or extends ESLint rules for specific folders.
+   */
+  "overrideRules": {
+    "contexts": {
+      "react-refresh/only-export-components": "off"
+    }
+  },
+
+  /**
+   * packageImportRules
+   *   type (optional)
+   *   - {
+   *       name: string;           // npm package name
+   *       importNames?: string[]; // Restrict specific named imports only.
+   *                               // If omitted, the entire package is restricted
+   *       allowedInFolders: F[];  // Folders where this import is allowed
+   *     }[]
+   *
+   * Restricts specific packages or named imports to designated folders only.
+   */
+  "packageImportRules": [
+    {
+      "name": "react",
+      "importNames": ["createContext"],
+      "allowedInFolders": ["contexts"]
+    },
+    {
+      "name": "react",
+      "importNames": ["useContext"],
+      "allowedInFolders": ["hooks"]
+    }
+  ]
+}
+```
+
+The `dependencyFlow` configuration above produces the following Mermaid flowchart:
+
+```mermaid
+flowchart TD
+  pages --> containers
+  containers --> | Only Provider | contexts
+  containers --> components
+  components --> hooks
+  hooks --> | Only Context | contexts
+```
+
+Based on the `markerTag` configuration, the CLI will locate and overwrite the following block in the target Markdown file:
+
+```md
+<!-- DEPENDENCY_RULE:START -->
+<!-- DEPENDENCY_RULE:END -->
+```
+
+## 🧠 Philosophy
+
+`@kekkai/structure-lint` treats folder structure as architecture.
+
+You define the dependency rules.  
+ESLint enforces them.  
+Documentation stays in sync.
+
+Designed for teams that care about **clarity**, **maintainability**,  
+and **long-term structural consistency**.

package/README.zh-TW.md

@@ -0,0 +1,249 @@
+[English](https://github.com/taco3064/kekkai-structure-lint/blob/main/README.md) | **繁體中文**
+
+# 📦 @kekkai/structure-lint
+
+一個 **config-driven** 的 ESLint 結構規則產生器，用來強制專案遵守 **單向資料夾依賴（One-way Dependency Flow）**，並提供獨立 CLI 來同步與驗證專案文件中的依賴規則說明。
+
+## 🔍 What Problem Does This Solve?
+
+在中大型前端專案中，資料夾結構往往隨著功能成長而逐漸失控：
+
+- 模組之間可以隨意互相 import
+- 相對路徑（../）跨層引用，難以追蹤實際依賴關係
+- 架構規則只存在於文件，無法被工具驗證
+- 文件與實際程式碼逐漸脫節
+
+@kekkai/structure-lint 的目的不是「規範寫法」，而是 **把資料夾結構與依賴方向，轉換成可被 ESLint 強制執行的規則**。
+
+> ⚠️ **ESLint v9+ Required**
+>
+> 本套件基於 **ESLint Flat Config** 設計，  
+> 僅支援 **ESLint v9 以上版本**。
+>
+> 如果你的專案仍使用 `.eslintrc`（legacy config），  
+> 請先升級至 Flat Config 架構後再使用本套件。
+
+## ✨ Core Ideas
+
+這個套件建立在三個核心概念之上：
+
+1. **Folder-as-a-Module**
+   - 每個子資料夾視為一個獨立模組（例如 `hooks/useShuffleCards`、`components/Card`）
+   - 建議使用 `index.ts` 作為模組入口，讓引用點一致且可讀
+
+2. **One-way Dependency Flow**
+   - 依賴關係以「資料夾層級」定義：每個資料夾只能依賴允許的下游資料夾
+   - 不允許逆向依賴，也不允許跨層跳轉
+
+3. **Enforceable Imports (Alias-only Cross-folder Imports)**
+   - 模組內部允許相對路徑（`./`）
+   - 跨資料夾引用一律使用專案 alias（例如 `~app/...`），避免 `../` 形成不可控的捷徑依賴
+
+> 🗂️ **Example Folder Structure:**
+>
+> ```text
+> src/
+> ├─ components/
+> │  └─ Card/
+> │     ├─ Component.tsx
+> │     ├─ index.ts
+> │     └─ types.ts
+> ├─ containers/
+> │  └─ DeckDrawStage/
+> │     ├─ Container.tsx
+> │     ├─ index.ts
+> │     └─ types.ts
+> └─ main.tsx
+> ```
+
+## 📥 Installation
+
+```bash
+npm install -D @kekkai/structure-lint
+# or
+pnpm add -D @kekkai/structure-lint
+# or
+yarn add -D @kekkai/structure-lint
+```
+
+本套件同時提供：
+
+- ESLint Flat Config 的設定產生器
+- 一個獨立的 CLI，用於文件同步與驗證
+
+## 🚀 Quick Start
+
+- **eslint.config.(js|ts)**
+  `@kekkai/structure-lint` 支援兩種使用方式，請依專案需求選擇最合適的模式：
+
+  ```ts
+  import { defineConfig } from 'eslint/config';
+  import { createStructureLint } from '@kekkai/structure-lint';
+
+  export default defineConfig([
+    // Options 1. 使用 structure.config.json
+    ...createStructureLint(),
+
+    // Options 2. 直接在 eslint.config.ts 中定義規則
+    ...createStructureLint({
+      appAlias: '~app',
+      lintFiles: 'src/{folder}/**/*.{ts,tsx}',
+      dependencyFlow: [
+        ['pages', 'layouts'],
+        ['layouts', 'containers'],
+        ['containers', 'components'],
+        ['components', 'hooks'],
+      ],
+    }),
+  ]);
+  ```
+
+- **CLI**
+  `@kekkai/structure-lint` 提供獨立的 CLI，用來將 Dependency Flow 規則同步到指定的 Markdown 文件 中。
+  ```bash
+  npx structure-lint
+  ```
+  > 💡 CLI 僅會讀取 structure.config.json。
+
+## 🧩 structure.config.json
+
+structure.config.json 用來定義專案的 資料夾依賴規則 與 文件同步設定。此檔案會同時被：
+
+- ESLint 設定 (createStructureLint())
+- CLI (npx structure-lint)
+
+所讀取。
+
+### 🔧 Configuration Options
+
+```ts
+{
+  /**
+   * appAlias
+   *   type (required):
+   *   - string
+   *
+   * 專案使用的模組 alias，用於強制跨資料夾 import 時的統一路徑格式。
+   * - 所有跨 folder 的 import 必須 使用此 alias
+   * - 用來取代不安全、不可控的 `../` 相對路徑
+   */
+  "appAlias": "~app",
+
+  /**
+   * lintFiles
+   *   type (required):
+   *   - string | string[]
+   *
+   * 指定 ESLint 要套用結構規則的檔案路徑。
+   * - 必須包含 `{folder}` 佔位符
+   * - `{folder}` 會在執行時自動替換為 dependencyFlow 中的每個資料夾名稱
+   */
+  "lintFiles": "src/{folder}/**/*.{ts,tsx}",
+
+  /**
+   * dependencyFlow
+   *   type (required):
+   *   - [
+   *       string, // from folder
+   *       string, // to folder
+   *       {
+   *         description?: string; // 僅用於文件輸出（Mermaid flowchart 註解），不影響 ESLint 規則
+   *         selfOnly?: boolean;   // true 表示 from folder 只能直接依賴 to folder，不可再往下延伸依賴鏈
+   *       }?
+   *     ][]
+   *
+   * 定義資料夾之間的 單向依賴關係。
+   */
+  "dependencyFlow": [
+    ["pages", "containers"],
+    ["containers", "contexts", { description: "Only Provider" }],
+    ["containers", "components"],
+    ["components", "hooks"],
+    ["hooks", "contexts", { description: "Only Context", selfOnly: true }],
+  ],
+
+  /**
+   * docs
+   *   type (optional)
+   *   - {
+   *       file: string;      // 要寫入的 Markdown 檔案路徑
+   *       markerTag: string; // 用來標記自動產生區塊的識別字
+   *       content?: string;  // 自定義文件說明內容
+   *     }
+   *
+   * 設定 CLI 用來 同步 dependencyFlow 至 Markdown 文件。
+   */
+  "docs": {
+    "file": "README.md",
+    "markerTag": "DEPENDENCY_RULE"
+  },
+
+  /**
+   * overrideRules
+   *   type (optional)
+   *   - {
+   *       [key: string]:       // key 必須是 dependencyFlow 中出現過的資料夾名稱
+   *         EslintRulesConfig; // value 為 ESLint rules 設定物件
+   *     }
+   *
+   * 為特定資料夾覆寫或補充 ESLint 規則。
+   */
+  "overrideRules": {
+    "contexts": {
+      "react-refresh/only-export-components": "off
+    }
+  },
+
+  /**
+   * packageImportRules
+   *   type (optional)
+   *   - {
+   *       name: string;           // npm 套件名稱
+   *       importNames?: string[]; // 僅限制指定的 named imports。若省略，則限制整個套件
+   *       allowedInFolders: F[];  // 允許使用該套件的資料夾清單
+   *     }[]
+   *
+   * 限制 特定套件或特定 import 成員 只能在指定資料夾中使用。
+   */
+  "packageImportRules": [
+    {
+      "name": "react",
+      "importNames": ["createContext"],
+      "allowedInFolders": ["contexts"]
+    },
+    {
+      "name": "react",
+      "importNames": ["useContext"],
+      "allowedInFolders": ["hooks"]
+    }
+  ]
+}
+```
+
+`dependencyFlow` 設定對應的 mermaid flowchart 如下:
+
+```mermaid
+flowchart TD
+  pages --> containers
+  containers --> | Only Provider | contexts
+  containers --> components
+  components --> hooks
+  hooks --> | Only Context | contexts
+```
+
+以範例中 `markerTag` 的設定，CLI 會尋找以下區塊並覆寫內容：
+
+```md
+<!-- DEPENDENCY_RULE:START -->
+<!-- DEPENDENCY_RULE:END -->
+```
+
+## 🧠 Philosophy
+
+`@kekkai/structure-lint` 將資料夾結構視為架構本身。
+
+由你定義依賴規則，  
+由 ESLint 強制執行，  
+並確保文件與實際架構保持同步。
+
+適合重視**可讀性、可維護性**與**長期結構一致性**的團隊。

package/dist/bin.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import ora from "ora";
+import path from "node:path";
+import cacache from "cacache";
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { execSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+//#region src/bin/utils.ts
+const CACHE_PATH = path.resolve(process.cwd(), "node_modules/.cache/kekkai");
+const CACHE_KEY = "dependency-flowchart-hash";
+const DEFAULT_CONTENT = `
+This project follows a **One-way Dependency Flow** principle:
+
+- Each folder may only import modules that lie downstream along the arrow direction
+- Upstream or reverse imports are not allowed
+
+> This rule is also enforced via **ESLint**.
+`;
+function isCliEntry(argv1) {
+	return argv1 && import.meta.url === pathToFileURL(argv1).href;
+}
+async function generateDocs({ dependencyFlow, docs, prettier }) {
+	const marker = getMarker(docs.markerTag);
+	if (isDocsValid(docs, marker.regex)) {
+		const { content = DEFAULT_CONTENT } = docs;
+		const docsFile = fs.readFileSync(path.resolve(process.cwd(), docs.file), "utf-8");
+		fs.writeFileSync(path.resolve(process.cwd(), docs.file), [
+			docsFile.slice(0, docsFile.indexOf(marker.tag[0]) + marker.tag[0].length),
+			"```mermaid",
+			"flowchart TD",
+			...dependencyFlow.map(([from, to, options]) => `  ${from} ${!options?.description ? "" : `-- ${options.description} `}--> ${to}`),
+			"```",
+			content,
+			docsFile.slice(docsFile.indexOf(marker.tag[1]))
+		].join("\n"));
+		if (fs.existsSync(prettier)) try {
+			execSync(`"${prettier}" --write "${docs.file}"`, { stdio: "inherit" });
+		} catch {
+			console.warn("Prettier formatting failed for the documentation file.");
+		}
+		await makeCache(dependencyFlow);
+	}
+}
+async function makeCache(flowchart) {
+	const hash = createHash("sha256").update(JSON.stringify(flowchart.slice().sort(([f1, t1], [f2, t2]) => f1.localeCompare(f2) || t1.localeCompare(t2)))).digest("hex");
+	if (await cacache.get(CACHE_PATH, CACHE_KEY).then(({ data }) => data.toString("utf-8")).catch(() => null) === hash) return;
+	await cacache.put(CACHE_PATH, CACHE_KEY, hash);
+}
+function getMarker(markerTag) {
+	return {
+		tag: [`<!-- ${markerTag}:START -->`, `<!-- ${markerTag}:END -->`],
+		regex: [/* @__PURE__ */ new RegExp(`<!--\\s*${markerTag}:START\\s*-->`), /* @__PURE__ */ new RegExp(`<!--\\s*${markerTag}:END\\s*-->`)]
+	};
+}
+function isDocsValid({ file, markerTag }, [startRegex, endRegex]) {
+	let docs;
+	try {
+		docs = fs.readFileSync(path.resolve(process.cwd(), file), "utf-8");
+	} catch {
+		throw new Error(`The specified documentation file "${file}" does not exist.`);
+	}
+	if (!startRegex.test(docs)) throw new Error(`The start marker must be "<!-- ${markerTag}:START -->" in the documentation file.`);
+	else if (!endRegex.test(docs)) throw new Error(`The end marker must be "<!-- ${markerTag}:END -->" in the documentation file.`);
+	return true;
+}
+
+//#endregion
+//#region src/lint/utils.ts
+const LINT_FILES_REGEX = /\{\s*folder\s*\}/;
+function extractAllFolders(dependencyFlow) {
+	return Array.from(new Set(dependencyFlow.flatMap(([from, to]) => [from, to])));
+}
+function loadStructureConfig(defaultConfigPath = "structure.config.json") {
+	const configPath = path.resolve(process.cwd(), defaultConfigPath);
+	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 }) {
+	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");
+	else if (typeof item[0] !== "string" || typeof item[1] !== "string" || !item[0]?.trim() || !item[1]?.trim()) throw new Error("Each tuple in dependencyFlow must have non-empty string values for the first two elements in structure.config.json");
+	else if (item.length > 2 && typeof item[2] !== "object") throw new Error("The third element in the dependencyFlow tuple must be an object if provided in structure.config.json");
+	const folders = extractAllFolders(dependencyFlow);
+	if (docs) {
+		const { file, markerTag, content } = docs;
+		if (typeof file !== "string" || !file?.trim()) throw new Error("docs.file is required in structure.config.json if docs is provided");
+		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");
+	}
+	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");
+		else if (entries.some(([_, rules]) => rules && typeof rules !== "object")) throw new Error("overrideRules values must be objects in structure.config.json");
+	}
+	if (packageImportRules) {
+		if (!Array.isArray(packageImportRules)) throw new Error("packageImportRules must be an array in structure.config.json");
+		for (const rule of packageImportRules) {
+			const { name, importNames, allowedInFolders } = rule || {};
+			if (typeof name !== "string" || !name?.trim()) throw new Error("Each packageImportRule must have a non-empty name property in structure.config.json");
+			else if (Array.isArray(importNames) && importNames.length && importNames.some((name$1) => typeof name$1 !== "string" || !name$1?.trim())) throw new Error("importNames in packageImportRule must be an array of non-empty strings in structure.config.json");
+			else if (!Array.isArray(allowedInFolders) || allowedInFolders.length === 0) throw new Error("allowedInFolders in packageImportRule must be a non-empty array in structure.config.json");
+			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,
+		overrideRules,
+		packageImportRules
+	};
+}
+
+//#endregion
+//#region src/bin/main.ts
+async function run() {
+	const spinner = ora("Generating Docs Content...").start();
+	let config;
+	try {
+		config = loadStructureConfig();
+		spinner.succeed("structure.config.json loaded successfully.");
+	} catch (e) {
+		spinner.fail(`Failed to load structure.config.json: ${e.message}`);
+		return 1;
+	}
+	if (!config.docs) {
+		spinner.info("No docs config found. Skip docs generation.");
+		return 0;
+	}
+	const { dependencyFlow, docs } = config;
+	try {
+		await generateDocs({
+			dependencyFlow,
+			docs,
+			prettier: path.resolve(process.cwd(), "node_modules/.bin/prettier")
+		});
+		spinner.succeed("Docs generated successfully.");
+		return 0;
+	} catch (e) {
+		spinner.fail(`Failed to generate docs: ${e.message}`);
+		return 1;
+	}
+}
+if (isCliEntry(process.argv[1])) run().then((code) => process.exit(code));
+
+//#endregion
+export { run };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './main';
+export type { DefineOptions, DependencyFlow } from './types';

package/dist/index.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+
+//#region src/lint/utils.ts
+const LINT_FILES_REGEX = /\{\s*folder\s*\}/;
+function extractAllFolders(dependencyFlow) {
+	return Array.from(new Set(dependencyFlow.flatMap(([from, to]) => [from, to])));
+}
+function getDisableFolderImports(config, folders, folder) {
+	const allowedFolders = (function getAllowedFolders(config$1, folder$1, root) {
+		return config$1.reduce((acc, [from, to, options]) => {
+			if (from === folder$1) {
+				if (!options?.selfOnly || root) acc.push(to, ...getAllowedFolders(config$1, to, false));
+			}
+			return acc;
+		}, []);
+	})(config, folder, true);
+	return folders.filter((f) => !allowedFolders.includes(f) && f !== folder);
+}
+function getLintFiles(folder, lintFiles) {
+	return (Array.isArray(lintFiles) ? lintFiles : [lintFiles]).map((file) => file.replace(LINT_FILES_REGEX, folder));
+}
+function loadStructureConfig(defaultConfigPath = "structure.config.json") {
+	const configPath = path.resolve(process.cwd(), defaultConfigPath);
+	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 }) {
+	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");
+	else if (typeof item[0] !== "string" || typeof item[1] !== "string" || !item[0]?.trim() || !item[1]?.trim()) throw new Error("Each tuple in dependencyFlow must have non-empty string values for the first two elements in structure.config.json");
+	else if (item.length > 2 && typeof item[2] !== "object") throw new Error("The third element in the dependencyFlow tuple must be an object if provided in structure.config.json");
+	const folders = extractAllFolders(dependencyFlow);
+	if (docs) {
+		const { file, markerTag, content } = docs;
+		if (typeof file !== "string" || !file?.trim()) throw new Error("docs.file is required in structure.config.json if docs is provided");
+		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");
+	}
+	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");
+		else if (entries.some(([_, rules]) => rules && typeof rules !== "object")) throw new Error("overrideRules values must be objects in structure.config.json");
+	}
+	if (packageImportRules) {
+		if (!Array.isArray(packageImportRules)) throw new Error("packageImportRules must be an array in structure.config.json");
+		for (const rule of packageImportRules) {
+			const { name, importNames, allowedInFolders } = rule || {};
+			if (typeof name !== "string" || !name?.trim()) throw new Error("Each packageImportRule must have a non-empty name property in structure.config.json");
+			else if (Array.isArray(importNames) && importNames.length && importNames.some((name$1) => typeof name$1 !== "string" || !name$1?.trim())) throw new Error("importNames in packageImportRule must be an array of non-empty strings in structure.config.json");
+			else if (!Array.isArray(allowedInFolders) || allowedInFolders.length === 0) throw new Error("allowedInFolders in packageImportRule must be a non-empty array in structure.config.json");
+			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,
+		overrideRules,
+		packageImportRules
+	};
+}
+
+//#endregion
+//#region src/lint/main.ts
+function createStructureLint({ appAlias, dependencyFlow, lintFiles, overrideRules, packageImportRules } = loadStructureConfig()) {
+	const folders = extractAllFolders(dependencyFlow);
+	return folders.map((folder) => {
+		const disableFolderImports = getDisableFolderImports(dependencyFlow, folders, folder);
+		const disablePackageImports = packageImportRules?.filter(({ allowedInFolders }) => !allowedInFolders.includes(folder));
+		return {
+			files: getLintFiles(folder, lintFiles),
+			rules: {
+				...overrideRules?.[folder],
+				"no-restricted-imports": ["error", {
+					patterns: [
+						{
+							group: ["../*/**"],
+							message: "\n🚫 Do not import from upper-level directories. Use the project alias (e.g. \"~app/*\") to follow the dependency flow."
+						},
+						{
+							group: [`${appAlias}/${folder}/**`],
+							message: "\n🚫 Do not import modules from the same layer. Extract shared logic into a lower-level folder if needed."
+						},
+						...!disableFolderImports.length ? [] : [{
+							group: disableFolderImports.map((banFolder) => `${appAlias}/${banFolder}/**`),
+							message: "\n🚫 This import violates the folder dependency rule. Only import from allowed lower-level folders."
+						}]
+					],
+					...disablePackageImports?.length && { paths: disablePackageImports.map(({ name, importNames }) => ({
+						name,
+						importNames,
+						message: importNames?.length ? `\n🚫 Do not import ${importNames.join(", ")} from "${name}" in this layer.` : `\n🚫 Do not import "${name}" in this layer.`
+					})) }
+				}]
+			}
+		};
+	});
+}
+
+//#endregion
+export { createStructureLint };

package/dist/main.d.ts

@@ -0,0 +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;

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { RulesConfig } from '@eslint/core';
+interface PackageImportRule<F extends string> {
+    name: string;
+    importNames?: string[];
+    allowedInFolders: F[];
+}
+export interface DocsOptions {
+    file: string;
+    markerTag: string;
+    content?: string;
+}
+export type DependencyFlow<F extends string> = [
+    F,
+    F,
+    {
+        description?: string;
+        selfOnly?: boolean;
+    }?
+];
+export interface DefineOptions<F extends string> {
+    appAlias: string;
+    dependencyFlow: DependencyFlow<F>[];
+    docs?: DocsOptions;
+    lintFiles: string | string[];
+    overrideRules?: Partial<Record<F, Partial<RulesConfig>>>;
+    packageImportRules?: PackageImportRule<F>[];
+}
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from 'type-fest';
+import type { DefineOptions, DependencyFlow } from './types';
+export declare function extractAllFolders<F extends string>(dependencyFlow: DependencyFlow<F>[]): F[];
+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>;

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@kekkai/structure-lint",
+  "version": "0.0.6",
+  "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",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "structure-lint": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslint-config",
+    "eslint-flat-config",
+    "architecture",
+    "project-structure",
+    "folder-structure",
+    "dependency-flow",
+    "one-way-dependency",
+    "import-rules",
+    "no-restricted-imports",
+    "config-driven",
+    "code-quality",
+    "maintainability"
+  ],
+  "author": "tabacotaco",
+  "homepage": "https://github.com/taco3064/kekkai-structure-lint#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taco3064/kekkai-structure-lint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/taco3064/kekkai-structure-lint/issues"
+  },
+  "scripts": {
+    "build": "rm -rf dist && rolldown -c rolldown.config.ts && tsc -b tsconfig.types.json --force",
+    "changeset": "changeset",
+    "commit": "cz",
+    "lint": "eslint .",
+    "pre-release": "node ./.changeset/pre-release.mjs",
+    "prepare": "husky",
+    "test": "vitest run --coverage",
+    "tsc": "tsc -p tsconfig.lib.json"
+  },
+  "dependencies": {
+    "cacache": "^20.0.3",
+    "ora": "^9.0.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^9.39.2",
+    "@types/cacache": "^20.0.0",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "commitizen": "^4.3.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "rolldown": "^1.0.0-beta.57",
+    "type-fest": "^5.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^4.0.16"
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix"
+    ]
+  }
+}