@no-k/hermes 0.2.0 → 0.3.0

package/README.md

@@ -42,7 +42,7 @@ chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
 `--dir`는 현재 작업 디렉터리 기준 상대 경로나 절대 경로를 받습니다.
 공백이 있는 경로는 따옴표로 감싸세요. 그 아래에는 유틸의 카테고리/이름 구조를 유지합니다.
 경로 입력의 초기값은 `--dir` → 현재 디렉터리의 저장된 설정 → 기본 경로 순서입니다.
-Core 기본값은 `src/utils/hermes`, 라이브러리는 `src/lib/hermes`이고 화면에서 각각 수정할 수 있습니다.
+Core 기본값은 `src/utils/hermes`, 라이브러리는 `libs/hermes`이고 화면에서 각각 수정할 수 있습니다.
 경로 입력에서 Enter는 현재 값 사용, Ctrl+U는 전체 지우기, Esc는 이전 화면입니다.
 모노레포에서는 설치할 앱·패키지 디렉터리에서 실행합니다. 상위 디렉터리의 설정은 찾지 않습니다.
 설정 파일이나 package.json이 없는 디렉터리에서도 파일 생성이 가능합니다.
@@ -82,7 +82,7 @@ npx @no-k/hermes@0.1.0 add array-chunk --dir "src/my utilities" --dry-run
 ## 항목과 의존성
 
 항목 이름은 core 디렉터리 경로를 하이픈으로 연결한 이름입니다.
-Tailwind 항목에는 tailwindcss- 접두어를 붙입니다.
+라이브러리 항목에는 tailwindcss-, lint-처럼 라이브러리 이름 접두어를 붙입니다.
 
 | 항목 | 포함하는 소스 |
 | --- | --- |
@@ -92,6 +92,7 @@ Tailwind 항목에는 tailwindcss- 접두어를 붙입니다.
 | tailwindcss-cn | 클래스 병합과 설정 |
 | tailwindcss-create-tailwind-css | 설정을 공유하는 cn·classVariant |
 | string-uuid | Node.js UUID 생성 |
+| lint-fsd | 수정 가능한 FSD ESLint 플러그인 소스 |
 
 core 항목은 외부 런타임 npm 의존성이 없습니다.
 Tailwind 항목은 clsx, tailwind-merge, tailwind-variants 중 해당 항목이 참조하는 패키지가 필요합니다.
@@ -109,6 +110,37 @@ string-uuid는 정적 node:crypto import 때문에 Node.js에서 사용해야
 dom-* 항목에는 DOM API와 DOM TypeScript 타입이 필요합니다.
 현재 Tailwind 헬퍼의 병합 규칙은 Tailwind CSS 4 기준입니다.
 
+## FSD lint 소스 생성
+
+이 항목이 포함된 Hermes 릴리스 배포 후 사용합니다.
+
+```bash
+npx @no-k/hermes@latest add lint-fsd
+pnpm add -D eslint typescript-eslint typescript jiti@^2.2.0 @types/node@^22
+```
+
+`libs/hermes/lint/fsd/`에 TypeScript 플러그인 진입점, 옵션, 경로 정책과 세 규칙을 생성합니다.
+기존 프로젝트에 저장된 라이브러리 경로가 있으면 그 값을 사용합니다.
+이번 설치 경로를 지정하려면 `--dir libs/hermes`를 붙이세요.
+레이어 의존 방향·slice 격리, public API와 디렉터리 구조를 검사합니다.
+생성된 파일은 직접 수정할 수 있으며, 다시 설치할 때도 변경된 파일은 기본 유지합니다.
+ESLint 설정과 package.json은 직접 연결합니다.
+
+```ts
+// eslint.config.ts
+import tseslint from "typescript-eslint";
+import fsd from "./libs/hermes/lint/fsd";
+
+export default [...tseslint.configs.recommended, fsd.configs.recommended];
+```
+
+기존 flat config에는 `fsd.configs.recommended`를 추가하세요.
+기본 FSD 루트는 린터 실행 위치 기준 `src`이고 alias는 `@`·`~`입니다.
+다른 구조는 `createConfig({ roots, aliases, layers })`로 지정할 수 있습니다.
+TypeScript 설정 로딩에 사용하는 `jiti`는 2.2 이상이 필요합니다.
+옵션, 규칙 수정 위치와 같은 소스를 사용하는 Oxlint 설정은
+[FSD 모듈 문서](https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd)를 참고하세요.
+
 ## 업데이트와 라이선스
 
 새 유틸을 찾을 때는 `@latest`로 최신 CLI에 포함된 카탈로그를 탐색합니다.
@@ -161,6 +193,7 @@ CLI 소스와 관련 도구는 이 패키지 안에서 TypeScript로 관리합
 | `scripts/preview-ui.ts` | 파일을 생성하지 않는 개발용 선택 화면 미리보기 |
 | `scripts/pack-cli.ts` | npm tarball 생성 및 포함 파일 검증 |
 | `scripts/smoke-cli.ts` | tarball을 설치해 소비 프로젝트에서 컴파일·실행 |
+| `scripts/smoke-fsd.ts` | CLI로 lint 소스를 생성하고 ESLint·Oxlint 실행, 직접 수정과 재설치 보존 검증 |
 | `test/*.test.ts` | CLI·catalog·패키징 회귀 테스트 |
 
 대화형 설치는 [단계별 계약](docs/interactive-install.md)에 따라 설치 엔진·설정, 카탈로그 탐색,
@@ -209,6 +242,7 @@ pnpm run test:run
 pnpm run check:cli
 pnpm run pack:cli
 pnpm run test:cli-install
+pnpm run test:fsd-install
 ```
 
 `tsconfig.json`은 런타임·도구·테스트 전체를 strict 및 `noUncheckedIndexedAccess`로 검사합니다.

package/catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "version": "0.2.0",
+  "version": "0.3.0",
   "items": [
     {
       "name": "algorithm-geometry-ccw",
@@ -1726,6 +1726,54 @@
         "http/status/status.ts"
       ]
     },
+    {
+      "name": "lint-fsd",
+      "packageName": "@hermes/lint-fsd",
+      "version": "0.1.0",
+      "modules": [
+        {
+          "name": "lint-fsd",
+          "packageName": "@hermes/lint-fsd",
+          "version": "0.1.0",
+          "scope": "lib",
+          "files": {
+            "lint/fsd/fsd.ts": "7bca7aae487a8d2bad71f2d152b8420a2cd7a8259c514224b6df764fe7642164",
+            "lint/fsd/import-listener.ts": "b07c96183e23f6e8902b1451fc350cd0eb5e87c0ed77626376fffa870c6434bc",
+            "lint/fsd/index.ts": "b5a08b38570e5094eacf089ecbe5bf0ac12692671bc266c923796172b8a436a8",
+            "lint/fsd/options.ts": "e24e3fb0cf0ab12cda93614ae19fcd1762d2b23c746a087390f612113195193b",
+            "lint/fsd/rules/fsd-layer-imports.ts": "23cee966cf7d230e2762c70d5c115fc49a26a9ccf8ba33a2d2bedb41f244ea0d",
+            "lint/fsd/rules/fsd-public-api.ts": "474eb3d91081db8b31a678990c19ddda346125a54c1a10a7cf7d2ed07eb41b28",
+            "lint/fsd/rules/fsd-slice-segments.ts": "57d72120b747d4d091ae09abc99e8f821c7ebca1ee4e992d1fc9fe1ab29ad275"
+          },
+          "requires": [
+            {
+              "packageName": "eslint",
+              "range": "^9.0.0 || ^10.0.0",
+              "kind": "peer",
+              "internal": false,
+              "optional": true
+            }
+          ]
+        }
+      ],
+      "scope": "lib",
+      "category": "lib/lint",
+      "description": "Feature-Sliced Design의 레이어 의존 방향, slice 경계, public API와 디렉터리 구조를 검사합니다. Hermes CLI가 규칙의 TypeScript 소스를 프로젝트에 생성합니다. 생성된 파일은 자유롭게 수정할 수 있습니다.",
+      "dependencies": [],
+      "runtime": "node",
+      "devDependencies": [
+        "@types/node@^22"
+      ],
+      "files": [
+        "lint/fsd/fsd.ts",
+        "lint/fsd/import-listener.ts",
+        "lint/fsd/index.ts",
+        "lint/fsd/options.ts",
+        "lint/fsd/rules/fsd-layer-imports.ts",
+        "lint/fsd/rules/fsd-public-api.ts",
+        "lint/fsd/rules/fsd-slice-segments.ts"
+      ]
+    },
     {
       "name": "number-clamp",
       "packageName": "@hermes/number-clamp",

package/dist/bin/hermes.js

@@ -25,7 +25,7 @@ const help = [
     "  -h, --help      Show help",
     "  -v, --version   Show version",
     "",
-    "Defaults: Core → src/utils/hermes; libraries → src/lib/hermes.",
+    "Defaults: Core → src/utils/hermes; libraries → libs/hermes.",
     "Saved paths are read from no-k.config.ts in the current directory.",
     "Run in an interactive terminal; choose No to edit your selection.",
     "External npm dependencies are reported; they are not installed automatically.",

package/dist/lib/contracts.js

@@ -1,4 +1,4 @@
 export const DEFAULT_INSTALL_DIRECTORIES = Object.freeze({
     core: "src/utils/hermes",
-    lib: "src/lib/hermes",
+    lib: "libs/hermes",
 });

package/docs/interactive-install.md

@@ -11,7 +11,7 @@
 첫 대분류는 사용자가 선택한 **Core / 라이브러리** 기준이며, 둘 다 선택할 수 있다.
 그다음 하위 분류도 별도 단계에서 선택한다.
 Core와 라이브러리의 설치 경로도 각각 지정할 수 있다.
-기본 경로는 Core가 src/utils/hermes, 라이브러리가 src/lib/hermes이며,
+기본 경로는 Core가 src/utils/hermes, 라이브러리가 libs/hermes이며,
 사용자는 Enter로 그대로 사용하거나 각각 수정할 수 있다.
 설치 시 no-k.config.ts를 생성해 프로젝트별 경로와 설치한 유틸 목록을 기억하고,
 다음 실행에서 경로를 복원하고 기존 설치 항목을 표시한다.
@@ -76,7 +76,7 @@ Core / 라이브러리를 첫 화면에서 고른 후 하위 분류도 별도
   경로는 요구하지 않는다.
 - 설정이 없을 때도 경로 입력란에 기본값을 제공한다. 사용자가 입력을 바꾸지 않고 Enter를
   누르면 표시된 경로를 사용하며, 최종 yes 후 설치가 성공하면 그 값을 설정 파일에 저장한다.
-- 기본 경로는 Core가 src/utils/hermes, 라이브러리가 src/lib/hermes다.
+- 기본 경로는 Core가 src/utils/hermes, 라이브러리가 libs/hermes다.
   코드에서는 DEFAULT_INSTALL_DIRECTORIES를 공통 정의로 사용한다.
 - 두 대분류에 같은 경로를 지정하는 것도 가능하다. 각 목적지 아래의 기존 유틸 상대 경로는 유지한다.
 - 단일 --dir 옵션은 양쪽 경로 입력의 공통 초기값으로 사용하고, 화면에서 각각 수정하는 것이
@@ -97,11 +97,11 @@ export default {
   schemaVersion: 1,
   directories: {
     core: "src/utils/hermes",
-    lib: "src/lib/hermes",
+    lib: "libs/hermes",
   },
   installed: [
     { name: "array-chunk", scope: "core", directory: "src/utils/hermes" },
-    { name: "tailwindcss-cn", scope: "lib", directory: "src/lib/hermes" },
+    { name: "tailwindcss-cn", scope: "lib", directory: "libs/hermes" },
   ],
 };
 ```
@@ -121,7 +121,7 @@ export default {
   기본 경로와 --dir, 화면에서 입력한 상대 경로, 설치 기록의 상대 경로에 같은 기준을 적용한다.
   절대 경로를 직접 지정하는 것도 가능하다.
 - **모노레포 사용**: 사용자가 설치할 앱·패키지 폴더에서 실행한다. 예를 들어 apps/web에서
-  실행하면 apps/web/no-k.config.ts와 그 아래 src/utils/hermes·src/lib/hermes를 사용한다.
+  실행하면 apps/web/no-k.config.ts와 그 아래 src/utils/hermes·libs/hermes를 사용한다.
   각 실행 위치의 설정과 설치 기록은 독립적이다.
 - **기존 파일 보존**: 로드 시 원문을 보관하고 CLI가 관리하는 필드만 갱신한다. 사용자 정의 필드와
   주석을 유지하며 경로 값, 설치 기록 추가와 버전 출처만 갱신한다. 안전하게 갱신할 수 없는 형식은 통째로 재생성하지
@@ -230,7 +230,7 @@ InstallRequest.fileDecisions에 유효한 replace 선택이 없는 충돌 파일
 | InstallWizardRequest | 초기 선택 ID, --dir로 받은 공통 초기 경로, dry-run과 초기 화면에서 처리할 overwrite 옵션 |
 | UtilityScope | 첫 대분류 ID: core 또는 lib |
 | CatalogCategoryId | 대분류를 포함한 하위 분류 ID: core/array, core/data-structure, lib/tailwindcss 등 |
-| DEFAULT_INSTALL_DIRECTORIES | 최초 경로 기본값: core는 src/utils/hermes, lib는 src/lib/hermes |
+| DEFAULT_INSTALL_DIRECTORIES | 최초 경로 기본값: core는 src/utils/hermes, lib는 libs/hermes |
 | InstallDirectories | 대분류별 경로. 아직 설정하지 않은 범위는 생략하며 core와 lib를 독립적으로 보관 |
 | InstalledItem | 설치한 유틸의 ID, 대분류와 설치 당시 목적지 |
 | ProjectConfig | no-k.config.ts의 스키마 버전, 대분류별 경로, 설치한 유틸 기록(installed) |

package/docs/module-versioning.md

@@ -1,11 +1,12 @@
 # 유틸 독립 버전 관리
 
-설치 가능한 유틸 디렉터리가 버전 단위다. 현재 Core 109개와 Tailwind 4개가 각각
+설치 가능한 유틸 디렉터리가 버전 단위다. 현재 Core 109개, Tailwind 4개, lint 1개가 각각
 `package.json`과 `CHANGELOG.md`를 가진다. 소스 파일을 옮기지 않아 기존 디렉터리의 Git 이력도 유지된다.
 같은 진입점에서 내보내는 함수·타입은 한 모듈이다. 예를 들어 heap·minHeap·maxHeap은
 `@hermes/data-structure-heap`의 공개 API로 함께 버전 관리한다.
 
-초기 버전은 기존 Core·Tailwind의 `1.0.0`을 이어받는다. 유틸은 `private: true` workspace 패키지로
+초기 버전은 기존 Core·Tailwind의 `1.0.0`을 이어받고, `lint-fsd`는 `0.1.0`에서 시작한다.
+유틸은 `private: true` workspace 패키지로
 관리하고 Changesets의 `privatePackages.version`을 활성화한다. 소스를 복사해 배포하므로
 각 유틸을 npm에 따로 publish하지 않는다. CLI `@no-k/hermes`의 버전은 별도로 관리한다.
 
@@ -90,7 +91,7 @@ codegen과 결과 확인이 성공한 뒤에만 설정을 저장한다. dry-run
 5. `pnpm install --lockfile-only`, `pnpm run check`, `pnpm run test:run`, `pnpm run check:cli`,
    `pnpm run test:cli-install`을 실행하고 결과와 변경 이력을 검토한다.
 
-`fixed`·`linked` 그룹은 없다. Core·Tailwind의 상위 집계 패키지와 개발 설정 패키지는 Changesets 대상에서
+`fixed`·`linked` 그룹은 없다. Core·Tailwind·lint의 상위 집계 패키지와 개발 설정 패키지는 Changesets 대상에서
 제외한다. 내부 의존성 변경에 따른 dependent 버전 증가는 Changesets 규칙을 따른다.
 자동으로 바뀐 의존 범위가 실제 API 호환성을 입증하지는 않으므로, major 변경 시 사용처 검증과
 필요한 명시적 major changeset도 작성해야 한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@no-k/hermes",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Add individual TypeScript utilities to your project with the Hermes CLI.",
   "license": "ISC",
   "files": ["dist", "templates", "catalog.json", "README.md", "LICENSE", "docs"],
@@ -23,6 +23,7 @@
     "preview:ui": "tsx scripts/preview-ui.ts",
     "pack:archive": "pnpm run build && node .build/scripts/pack-cli.js",
     "test:install": "pnpm run build && node .build/scripts/smoke-cli.js",
+    "test:fsd-install": "pnpm run build && node .build/scripts/smoke-fsd.js",
     "prepack": "pnpm run build"
   },
   "type": "module",

package/templates/lint/fsd/fsd.ts

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { DEFAULT_FSD_LAYERS, type FsdOptions } from "./options";
+
+// This module knows only paths and FSD policy. It does not depend on ESLint, ASTs or filesystem reads.
+export const toPosixPath = (value: string): string =>
+  value.replaceAll("\\", "/").replace(/^[a-z]:/, (drive) => drive.toUpperCase());
+
+export const resolvePath = (base: string, value: string): string => {
+  const windows = /^[a-z]:[/\\]/i.test(base) || /^[a-z]:[/\\]/i.test(value);
+  return toPosixPath((windows ? path.win32 : path.posix).resolve(toPosixPath(base), toPosixPath(value)));
+};
+
+const isWithin = (parent: string, child: string): boolean =>
+  child === parent || child.startsWith(parent.endsWith("/") ? parent : parent + "/");
+const sourceExtension = /(?:\.d)?\.[cm]?[jt]sx?$/;
+const withoutExtension = (name: string): string => name.replace(sourceExtension, "");
+const isFile = (name: string): boolean => /\.[^/]+$/.test(name);
+
+type Root = { path: string; aliases: [string, string][] };
+export type FsdLocation = {
+  root: string;
+  layer: string;
+  parts: string[];
+  slice?: string;
+  scope: string[];
+  segmentless: boolean;
+};
+export type FsdViolation = {
+  messageId: "invalidDirection" | "crossSliceSameLayer" | "usePublicApi" | "missingSlice" | "missingSegment";
+  data: Record<string, string>;
+};
+
+const normalizeAliases = (...groups: Record<string, string>[]): [string, string][] => {
+  const aliases = new Map<string, string>();
+  for (const group of groups) {
+    for (const [key, target] of Object.entries(group)) {
+      const prefix = key.replace(/\/\*$/, "").replace(/\/$/, "");
+      const destination = target.replace(/\/\*$/, "");
+      if (!prefix || prefix.includes("*") || destination.includes("*")) {
+        throw new Error("FSD aliases must be exact prefixes, optionally ending in /*.");
+      }
+      aliases.set(prefix, destination);
+    }
+  }
+  return [...aliases].sort(([a], [b]) => b.length - a.length);
+};
+
+export function createFsdPolicy(cwd: string, options: FsdOptions = {}) {
+  const layers = options.layers ?? DEFAULT_FSD_LAYERS;
+  const ranks = new Map(layers.map((layer, index) => [layer, index]));
+  const segmentlessLayers = options.segmentlessLayers ?? ["app", "shared"];
+  const publicApiFiles = options.publicApiFiles ?? ["index"];
+  const sharedModuleSegments = options.sharedModuleSegments ?? ["ui", "lib"];
+  const roots: Root[] = (options.roots ?? ["src"])
+    .map((root) => {
+      const definition = typeof root === "string" ? { path: root } : root;
+      return {
+        path: resolvePath(cwd, definition.path),
+        aliases: normalizeAliases({ "@": ".", "~": "." }, options.aliases ?? {}, definition.aliases ?? {}),
+      };
+    })
+    .sort((a, b) => b.path.length - a.path.length);
+  if (new Set(roots.map((root) => root.path)).size !== roots.length) {
+    throw new Error("FSD roots must resolve to different directories.");
+  }
+  const ignored = (options.ignore ?? []).map((prefix) => {
+    const normalized = toPosixPath(prefix).replace(/^\.\//, "").replace(/\/$/, "");
+    if (!normalized || normalized.startsWith("/") || normalized.includes("*") || normalized.split("/").includes("..")) {
+      throw new Error("FSD ignore paths must be root-relative file/directory prefixes without globs or '..'.");
+    }
+    return normalized;
+  });
+  const isPublicFile = (name: string): boolean => publicApiFiles.includes(withoutExtension(name));
+
+  function locate(filename: string): FsdLocation | undefined {
+    const absolute = resolvePath(cwd, filename);
+    const root = roots.find((candidate) => isWithin(candidate.path, absolute));
+    if (!root) return undefined;
+    const relative = absolute.slice(root.path.length).replace(/^\//, "");
+    if (ignored.some((prefix) => isWithin(prefix, relative))) return undefined;
+    const parts = relative.split("/").filter(Boolean);
+    const layer = parts[0];
+    if (!layer || !ranks.has(layer)) return undefined;
+    const segmentless = segmentlessLayers.includes(layer);
+    const scope = parts.slice(0, 2);
+    // Shared UI/lib modules may each have an index, avoiding one large segment barrel.
+    if (
+      layer === "shared" &&
+      sharedModuleSegments.includes(parts[1] ?? "") &&
+      parts[2] &&
+      !isFile(parts[2]) &&
+      !isPublicFile(parts[2])
+    ) {
+      scope.push(parts[2]);
+    }
+    return { root: root.path, layer, parts, slice: segmentless ? undefined : parts[1], scope, segmentless };
+  }
+
+  function resolveImport(source: string, importer: FsdLocation, filename: string): FsdLocation | undefined {
+    if (source.startsWith(".")) return locate(resolvePath(resolvePath(filename, ".."), source));
+    if (path.posix.isAbsolute(source) || path.win32.isAbsolute(source)) return locate(source);
+    const root = roots.find((candidate) => candidate.path === importer.root);
+    if (!root) return undefined;
+    for (const [alias, target] of root.aliases) {
+      if (source === alias || source.startsWith(alias + "/")) {
+        return locate(resolvePath(resolvePath(root.path, target), source.slice(alias.length).replace(/^\//, "")));
+      }
+    }
+    // Bare specifiers are npm packages unless explicitly mapped by the consumer.
+    return undefined;
+  }
+
+  const sameSlice = (from: FsdLocation, to: FsdLocation): boolean =>
+    from.root === to.root && from.layer === to.layer && from.slice !== undefined && from.slice === to.slice;
+  const sameScope = (from: FsdLocation, to: FsdLocation): boolean =>
+    from.root === to.root && from.scope.join("/") === to.scope.join("/");
+  const entityCrossApi = (from: FsdLocation, to: FsdLocation): boolean =>
+    (options.allowEntityCrossImports ?? true) &&
+    from.root === to.root &&
+    from.layer === "entities" &&
+    to.layer === "entities" &&
+    from.slice !== to.slice &&
+    to.parts.length === 4 &&
+    to.parts[2] === "@x" &&
+    withoutExtension(to.parts[3] ?? "") === from.slice;
+
+  function checkLayers(from: FsdLocation, to: FsdLocation): FsdViolation | undefined {
+    if ((ranks.get(to.layer) ?? -1) > (ranks.get(from.layer) ?? -1)) {
+      return { messageId: "invalidDirection", data: { fromLayer: from.layer, toLayer: to.layer } };
+    }
+    if (
+      from.layer === to.layer &&
+      !sameSlice(from, to) &&
+      !(from.segmentless && from.root === to.root) &&
+      !entityCrossApi(from, to) &&
+      !options.allowCrossSliceSameLayer &&
+      !(options.allowCrossSliceLayers ?? []).includes(from.layer)
+    ) {
+      return {
+        messageId: "crossSliceSameLayer",
+        data: {
+          fromLayer: from.layer,
+          fromSlice: from.slice ?? from.scope[1] ?? "",
+          toLayer: to.layer,
+          toSlice: to.slice ?? to.scope[1] ?? "",
+        },
+      };
+    }
+    return undefined;
+  }
+
+  function checkPublicApi(from: FsdLocation, to: FsdLocation): FsdViolation | undefined {
+    if (sameScope(from, to) || entityCrossApi(from, to)) return undefined;
+    const remainder = to.parts.slice(to.scope.length);
+    const publicScope = to.scope.length >= 2 && !isFile(to.scope[to.scope.length - 1] ?? "");
+    if (publicScope && (remainder.length === 0 || (remainder.length === 1 && isPublicFile(remainder[0] ?? "")))) {
+      return undefined;
+    }
+    return { messageId: "usePublicApi", data: { layer: to.layer, publicName: to.scope.slice(1).join("/") } };
+  }
+
+  function checkStructure(location: FsdLocation): FsdViolation | undefined {
+    if ((options.ignoreLayers ?? []).includes(location.layer)) return undefined;
+    const { parts, layer, segmentless } = location;
+    const filename = parts[parts.length - 1] ?? "";
+    if (segmentless) {
+      if (parts.length >= 3 || (parts.length === 2 && isPublicFile(filename))) return undefined;
+      return { messageId: "missingSegment", data: { layer, slice: "" } };
+    }
+    if (parts.length < 3) {
+      return { messageId: "missingSlice", data: { layer } };
+    }
+    if (parts.length === 3 && !isPublicFile(filename)) {
+      return { messageId: "missingSegment", data: { layer, slice: parts[1] ?? "" } };
+    }
+    return undefined;
+  }
+
+  return { locate, resolveImport, checkLayers, checkPublicApi, checkStructure };
+}

package/templates/lint/fsd/import-listener.ts

@@ -0,0 +1,41 @@
+import type { Rule } from "eslint";
+import { type FsdViolation, createFsdPolicy } from "./fsd";
+import type { FsdOptions } from "./options";
+
+type SourceNode = {
+  value?: unknown;
+  literal?: SourceNode;
+  source?: SourceNode;
+  argument?: SourceNode;
+};
+
+export function createImportListener(
+  context: Rule.RuleContext,
+  check: "checkLayers" | "checkPublicApi",
+): Rule.RuleListener {
+  const filename = context.filename;
+  if (!filename || filename.startsWith("<")) return {};
+  const policy = createFsdPolicy(context.cwd, context.options[0] as FsdOptions | undefined);
+  const from = policy.locate(filename);
+  if (!from) return {};
+  const visit = (node: Rule.Node): void => {
+    const candidate = node as unknown as SourceNode;
+    let source = candidate.source;
+    if (!source) {
+      const argument = candidate.argument;
+      source = argument?.literal ?? argument;
+    }
+    if (typeof source?.value !== "string") return;
+    const to = policy.resolveImport(source.value, from, filename);
+    if (!to) return;
+    const violation: FsdViolation | undefined = policy[check](from, to);
+    if (violation) context.report({ node: source as Rule.Node, ...violation });
+  };
+  return {
+    ImportDeclaration: visit,
+    ExportNamedDeclaration: visit,
+    ExportAllDeclaration: visit,
+    ImportExpression: visit,
+    TSImportType: visit,
+  };
+}

package/templates/lint/fsd/index.ts

@@ -0,0 +1,32 @@
+// Hermes copies this plugin into the consumer project. Edit these files to customize its policy.
+import type { Linter } from "eslint";
+import { type FsdOptions, HERMES_OPTIONS } from "./options";
+import fsdLayerImports from "./rules/fsd-layer-imports";
+import fsdPublicApi from "./rules/fsd-public-api";
+import fsdSliceSegments from "./rules/fsd-slice-segments";
+
+export type { FsdOptions, FsdRoot } from "./options";
+
+const plugin = {
+  meta: { name: "hermes-fsd" },
+  rules: {
+    "fsd-layer-imports": fsdLayerImports,
+    "fsd-public-api": fsdPublicApi,
+    "fsd-slice-segments": fsdSliceSegments,
+  },
+  configs: {} as { recommended: Linter.Config; hermes: Linter.Config },
+};
+
+export function createConfig(options: FsdOptions = {}, namespace = "fsd"): Linter.Config {
+  return {
+    name: "hermes-fsd/" + namespace,
+    files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+    plugins: { [namespace]: plugin },
+    rules: Object.fromEntries(Object.keys(plugin.rules).map((rule) => [namespace + "/" + rule, ["error", options]])),
+  };
+}
+
+plugin.configs.recommended = createConfig();
+plugin.configs.hermes = createConfig(HERMES_OPTIONS, "hermes");
+
+export default plugin;

package/templates/lint/fsd/options.ts

@@ -0,0 +1,74 @@
+export type FsdRoot = {
+  path: string;
+  /** Alias targets are relative to this FSD root, not the process cwd. */
+  aliases?: Record<string, string>;
+};
+
+export type FsdOptions = {
+  roots?: (string | FsdRoot)[];
+  aliases?: Record<string, string>;
+  /** Lowest to highest. Deprecated "processes" is opt-in. */
+  layers?: string[];
+  segmentlessLayers?: string[];
+  allowCrossSliceLayers?: string[];
+  allowCrossSliceSameLayer?: boolean;
+  allowEntityCrossImports?: boolean;
+  /** Root-relative file/directory prefixes, not globs. Applies to both ends of an import. */
+  ignore?: string[];
+  /** Only affects the structure rule. */
+  ignoreLayers?: string[];
+  /** Public entrypoint basenames, without extensions. */
+  publicApiFiles?: string[];
+  /** Shared segments whose child modules may expose their own public API. */
+  sharedModuleSegments?: string[];
+};
+
+export const DEFAULT_FSD_LAYERS = ["shared", "entities", "features", "widgets", "pages", "app"];
+
+export const HERMES_OPTIONS: FsdOptions = {
+  layers: ["shared", "entities", "features", "widgets", "pages", "processes", "app"],
+  allowCrossSliceLayers: ["widgets", "pages", "processes", "app"],
+  ignoreLayers: ["shared", "app"],
+};
+
+const names = {
+  type: "array",
+  items: { type: "string", pattern: "^[^/\\\\.*]+$" },
+  uniqueItems: true,
+};
+const aliases = {
+  type: "object",
+  additionalProperties: { type: "string", minLength: 1 },
+};
+
+export const optionSchema = {
+  type: "object",
+  properties: {
+    roots: {
+      type: "array",
+      minItems: 1,
+      items: {
+        anyOf: [
+          { type: "string", minLength: 1 },
+          {
+            type: "object",
+            properties: { path: { type: "string", minLength: 1 }, aliases },
+            required: ["path"],
+            additionalProperties: false,
+          },
+        ],
+      },
+    },
+    aliases,
+    layers: { ...names, minItems: 1 },
+    segmentlessLayers: names,
+    allowCrossSliceLayers: names,
+    allowCrossSliceSameLayer: { type: "boolean" },
+    allowEntityCrossImports: { type: "boolean" },
+    ignore: { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true },
+    ignoreLayers: names,
+    publicApiFiles: { ...names, minItems: 1 },
+    sharedModuleSegments: names,
+  },
+  additionalProperties: false,
+} as const;

package/templates/lint/fsd/rules/fsd-layer-imports.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "eslint";
+import { createImportListener } from "../import-listener";
+import { optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce FSD layer direction and slice isolation",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-layer-imports",
+    },
+    schema: [optionSchema],
+    messages: {
+      invalidDirection: "FSD layer '{{fromLayer}}' cannot import upper layer '{{toLayer}}'.",
+      crossSliceSameLayer:
+        "FSD same-layer imports must stay inside the same slice. '{{fromLayer}}/{{fromSlice}}' cannot import '{{toLayer}}/{{toSlice}}'.",
+    },
+  },
+  create: (context) => createImportListener(context, "checkLayers"),
+};
+
+export default rule;

package/templates/lint/fsd/rules/fsd-public-api.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "eslint";
+import { createImportListener } from "../import-listener";
+import { optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce public API imports across FSD scopes",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-public-api",
+    },
+    schema: [optionSchema],
+    messages: {
+      usePublicApi: "FSD cross-scope import must use the public API of '{{layer}}/{{publicName}}'.",
+    },
+  },
+  create: (context) => createImportListener(context, "checkPublicApi"),
+};
+
+export default rule;

package/templates/lint/fsd/rules/fsd-slice-segments.ts

@@ -0,0 +1,33 @@
+import type { Rule } from "eslint";
+import { createFsdPolicy } from "../fsd";
+import { type FsdOptions, optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce FSD slice/segment structure, including segment-only App and Shared",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-slice-segments",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingSlice: "FSD layer '{{layer}}' must contain slice directories before implementation files.",
+      missingSegment:
+        "FSD implementation in '{{layer}}/{{slice}}' must live in a segment or be an allowed public API entrypoint.",
+    },
+  },
+  create(context) {
+    if (!context.filename || context.filename.startsWith("<")) return {};
+    const policy = createFsdPolicy(context.cwd, context.options[0] as FsdOptions | undefined);
+    const location = policy.locate(context.filename);
+    if (!location) return {};
+    return {
+      Program(node) {
+        const violation = policy.checkStructure(location);
+        if (violation) context.report({ node, ...violation });
+      },
+    };
+  },
+};
+
+export default rule;