@3o3/eslint-config 0.2.0

package/README.md

@@ -0,0 +1,113 @@
+# @3o3/eslint-config
+
+3o3 공유 ESLint 설정(ESLint 9 flat config). **사용처에 따라 레이어를 골라** 쓴다.
+
+## 설치
+
+```sh
+pnpm add -D @3o3/eslint-config eslint typescript
+```
+
+`eslint` 와 `typescript` 는 peerDependency, 나머지 플러그인(typescript-eslint,
+eslint-plugin-react, react-hooks, import, @emotion, jsdoc, tsdoc, prettier)은 이
+패키지의 dependency 라 따로 설치할 필요가 없다.
+
+## 레이어
+
+| 레이어 | 내용 | 언제 |
+|---|---|---|
+| `base` | js + ts 공통(`@eslint/js` + `typescript-eslint` + `import`) + 3o3 하우스 규칙 | 모든 TS 코드(토대) |
+| `react` | `base` 위 React 델타(`eslint-plugin-react` + `react-hooks` + `@emotion`) | React 패키지/앱 |
+| `docs` | 공개 API 문서 완전성(`jsdoc` + `tsdoc`) — `src/**` 글롭, 내부는 파일 지시어로 opt-out | 공개 API 문서 강제 |
+| `all` | `base + react + prettier` 번들 | "전부 켜기" |
+| `prettier` | `eslint-config-prettier`(포매팅 충돌 규칙 off) | 항상 **마지막**에 스프레드 |
+
+`react` 는 `base` 위에 얹는 누적 델타다. 각 영역의 3o3 규칙을 이미 포함한다.
+전역 무시(dist/esm/비 ts·tsx)와 프로젝트 고유 규칙은 소비하는 쪽 config 에서 직접 둔다.
+
+## 사용법
+
+루트에 `eslint.config.mjs` 하나를 두는 **단일 설정**을 권장한다(이 모노레포도 동일).
+`defineConfig` + 문자열 `extends` 스타일(ESLint 가 미는 방식)을 기본으로 쓴다.
+default export 는 `configs` 맵을 가진 플러그인 형태(typescript-eslint /
+eslint-plugin-react 와 동일)라 `extends: ['@3o3/<layer>']` 로 참조된다.
+
+```js
+// eslint.config.mjs  (React 포함 레포)
+import { defineConfig } from 'eslint/config'
+import threeo3 from '@3o3/eslint-config'
+
+export default defineConfig([
+  // 전역 무시는 소비하는 쪽에서 직접 둔다(빌드 산출물 + 비 ts·tsx)
+  { ignores: ['**/dist/**', '**/esm/**', '**/*.{js,cjs,mjs,jsx,json}'] },
+  { plugins: { '@3o3': threeo3 }, extends: ['@3o3/base', '@3o3/react'] },
+  ...threeo3.docs(), // 공개 API 문서 검사(선택)
+  threeo3.prettier, // 항상 마지막
+])
+```
+
+```js
+// 플레인 TS 레포(React 없음) — react 레이어만 빼면 된다
+export default defineConfig([
+  { ignores: ['**/dist/**', '**/esm/**', '**/*.{js,cjs,mjs,jsx,json}'] },
+  { plugins: { '@3o3': threeo3 }, extends: ['@3o3/base'] },
+  threeo3.prettier,
+])
+```
+
+프로젝트 고유 규칙은 마지막(프리티어 앞)에 flat-config 객체로 직접 얹는다:
+```js
+  { files: ['**/*.{ts,tsx}'], rules: { 'no-console': 'error' } },
+  { files: ['scripts/**'], rules: { '@typescript-eslint/no-explicit-any': 'off' } },
+```
+
+### 배열 스프레드 스타일 (named export)
+
+`extends` 대신 배열을 직접 펼쳐도 된다.
+
+```js
+import { base, react, docs, prettier } from '@3o3/eslint-config'
+
+export default [
+  { ignores: ['**/dist/**', '**/esm/**', '**/*.{js,cjs,mjs,jsx,json}'] },
+  ...base,
+  ...react,
+  ...docs(),
+  prettier,
+]
+```
+
+## docs 레이어 — 공개 API 문서 강제 (글롭 + 지시어 opt-out)
+
+`docs()` 는 `src/**` 의 ts/tsx 에서 **export 된 함수·상수·인터페이스에 문서 블록을
+요구**한다(`jsdoc/require-jsdoc`). 즉 **"문서 필수가 기본값"**.
+
+내부 전용 모듈(배럴로 공개 안 하는 헬퍼)은 파일 **맨 위 한 줄**로 제외한다:
+```ts
+/* eslint-disable jsdoc/require-jsdoc -- 비공개(내부) 모듈: 공개 API 아님 */
+```
+- `jsdoc/require-jsdoc` 하나만 끄면 docs 강제가 통째로 꺼진다(base/react 등은 그대로).
+- `tsdoc/syntax` 는 같이 적지 말 것 — 그 파일에 TSDoc 주석이 없으면 "unused directive"
+  경고가 난다.
+
+`files` 글롭은 옵션으로 바꿀 수 있다: `docs({ files: ['packages/**/src/**/*.{ts,tsx}'] })`.
+기본은 `['**/src/**/*.{ts,tsx}']`(test/spec·stories·d.ts·`_internal` 자동 제외).
+
+### 왜 이 방식인가 (과거 re-export fs 스캔 대비)
+
+- **에디터 즉시 반영** — 정적 글롭이라 배럴을 바꿔도 ESLint 서버 재시작이 필요 없다.
+  (스캔 방식은 공개 목록을 config 로드 때 한 번 계산·캐시해서, 배럴 변경이 에디터에
+  반영되려면 재시작이 필요했다.)
+- **모르게 빠지지 않음** — 기본이 "문서 필수"라, 새 공개 파일은 자동으로 강제 대상.
+  내부 제외는 코드에 지시어로 **명시**되어 코드리뷰에서 보인다.
+- **런타임 fs 작업 없음** — docs 설정이 순수 정적.
+
+## 설계 메모
+
+- **타입 인지 규칙 미사용**: `recommended`(not type-checked)만 켠다 →
+  `parserOptions.project` 가 필요 없어 어떤 레포에서도 그대로 동작한다.
+- **무시·프로젝트 규칙은 소비처 config 에서**: base/react 는 순수 룰 레이어라 무시
+  규칙을 갖지 않는다. 전역 무시(dist/esm 등)와 프로젝트 고유 규칙은 소비하는 쪽
+  `eslint.config` 에서 직접 둔다.
+- **공개/내부 구분은 위치·지시어로** : 재export 그래프(동적)가 아니라 `src/**` 글롭 +
+  파일 지시어(정적)로 판정 → 예측 가능하고 에디터에 실시간.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@3o3/eslint-config",
+  "version": "0.2.0",
+  "description": "3o3 공유 ESLint 설정 — 사용처에 따라 레이어(base/react/docs/all)를 골라 쓴다.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./base": "./src/base.js",
+    "./react": "./src/react.js",
+    "./docs": "./src/docs.js",
+    "./all": "./src/all.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.jobis.co/jobisnvillains/3o3_libraries",
+    "directory": "configs/eslint-config"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@emotion/eslint-plugin": "^11.12.0",
+    "@eslint/js": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsdoc": "^63.0.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "globals": "^15.15.0",
+    "typescript-eslint": "^8.60.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9",
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/all.js

@@ -0,0 +1,23 @@
+import base from './base.js'
+import reactLayer from './react.js'
+import prettier from 'eslint-config-prettier'
+
+/**
+ * all 레이어 — 배터리 포함 번들.
+ *
+ * base + react 를 켜고 마지막에 eslint-config-prettier 로 포매팅 충돌 규칙을
+ * 끈다(반드시 마지막). "전부 켜고 싶다" 일 때 쓴다. 플레인 TS 라이브러리는
+ * react 규칙이 불필요하므로 base 만 권장.
+ *
+ * docs 레이어는 `packageDir`/`rootDir` 이 필요한 팩토리라 번들에 포함하지 않는다 —
+ * 필요하면 `docs({ packageDir })` 를 직접 스프레드한다.
+ *
+ * @example
+ * ```js
+ * import { all } from '@3o3/eslint-config'
+ * export default all
+ * ```
+ */
+const all = [...base, ...reactLayer, prettier]
+
+export default all

package/src/base.js

@@ -0,0 +1,115 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import importPlugin from 'eslint-plugin-import'
+import globals from 'globals'
+
+/**
+ * base 레이어 — js + ts 공통.
+ *
+ * 프레임워크에 무관한 3o3 공통 규칙의 단일 출처다.
+ *   · @eslint/js + typescript-eslint(recommended) + eslint-plugin-import
+ *   · 3o3 하우스 규칙(naming-convention / member-ordering / eqeqeq / curly 등)
+ *
+ * 타입 인지(type-aware) 규칙은 켜지 않는다 → `parserOptions.project` 가 필요 없어
+ * 어떤 레포에서도 그대로 동작한다(이식성).
+ *
+ * 모든 `@3o3/eslint-config` 소비의 토대. react 레이어는 이 위에 스프레드한다.
+ *
+ * @example
+ * ```js
+ * import { base } from '@3o3/eslint-config'
+ * export default [...base]
+ * ```
+ */
+const base = tseslint.config({
+  files: ['**/*.{ts,tsx}'],
+  extends: [
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+    importPlugin.flatConfigs.recommended,
+    importPlugin.flatConfigs.typescript,
+  ],
+  languageOptions: {
+    globals: {
+      ...globals.node,
+      ...globals.browser,
+      ...globals.jest,
+      ...globals.es2021,
+    },
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+  settings: {
+    'import/resolver': { typescript: {} },
+  },
+  rules: {
+    'no-implicit-coercion': 'error',
+    'no-warning-comments': [
+      'warn',
+      {
+        terms: ['TODO', 'FIXME', 'XXX', 'BUG'],
+        location: 'anywhere',
+      },
+    ],
+    curly: ['error', 'all'],
+    eqeqeq: ['error', 'always', { null: 'ignore' }],
+
+    // eslint-plugin-import recommended preset에서 신규 적용 — 기존 config는 import 규칙을 켜지 않았으므로 동작 보존 위해 off
+    // (import/export는 TS type re-export에 대한 오탐, 실제 중복 export는 tsc typecheck가 잡음)
+    'import/export': 'off',
+    'import/no-duplicates': 'off',
+
+    // Hoisting을 전략적으로 사용한 경우가 많아서
+    '@typescript-eslint/no-use-before-define': 'off',
+    // 모델 정의 부분에서 class와 interface를 합치기 위해 사용하는 용법도 잡고 있어서
+    // (v8에서 no-empty-interface는 no-empty-object-type으로 통합됨)
+    '@typescript-eslint/no-empty-object-type': 'off',
+    // 모델 정의 부분에서 파라미터 프로퍼티를 잘 쓰고 있어서
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    // (v8에서 no-var-requires는 no-require-imports로 통합됨, 기존 warn 의도 보존)
+    '@typescript-eslint/no-require-imports': 'warn',
+    '@typescript-eslint/no-non-null-asserted-optional-chain': 'warn',
+    // v5 recommended에는 있었으나 v8 recommended에서 빠진 규칙. 기존 동작(warn) 보존.
+    // (소스에 남아있는 eslint-disable @typescript-eslint/no-non-null-assertion 주석들이 이를 전제로 함)
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    '@typescript-eslint/no-inferrable-types': 'warn',
+    '@typescript-eslint/no-empty-function': 'off',
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
+        selector: 'variable',
+        leadingUnderscore: 'allow',
+      },
+      { format: ['camelCase', 'PascalCase'], selector: 'function' },
+      { format: ['PascalCase'], selector: 'interface' },
+      { format: ['PascalCase'], selector: 'typeAlias' },
+    ],
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/array-type': ['error', { default: 'array-simple' }],
+    '@typescript-eslint/no-unused-vars': [
+      'error',
+      // v8에서 caughtErrors 기본값이 'none' → 'all'로 바뀌어 catch (e) 바인딩까지 잡는다.
+      // 기존(v5) 동작 보존을 위해 caughtErrors를 'none'으로 복원.
+      { ignoreRestSiblings: true, caughtErrors: 'none' },
+    ],
+    '@typescript-eslint/member-ordering': [
+      'error',
+      {
+        default: [
+          'public-static-field',
+          'private-static-field',
+          'public-instance-field',
+          'private-instance-field',
+          'public-constructor',
+          'private-constructor',
+          'public-instance-method',
+          'private-instance-method',
+        ],
+      },
+    ],
+  },
+})
+
+export default base

package/src/docs.js

@@ -0,0 +1,75 @@
+import jsdoc from 'eslint-plugin-jsdoc'
+import tsdoc from 'eslint-plugin-tsdoc'
+
+const disabledJsdocRules = {
+  // ── 타입 그룹: 주석에 타입을 요구/검증/삭제하는 룰. TS에선 전부 OFF ──
+  'jsdoc/require-param-type': 'off',
+  'jsdoc/require-returns-type': 'off',
+  'jsdoc/require-property-type': 'off',
+  'jsdoc/no-defaults': 'off', // 기본값도 코드에서. fixer가 내용 삭제
+  'jsdoc/no-undefined-types': 'off', // TS에서 오탐 많음
+  'jsdoc/valid-types': 'off',
+  'jsdoc/check-types': 'off',
+  'jsdoc/type-formatting': 'off',
+  'jsdoc/reject-function-type': 'off',
+  // ── 태그 이름 검증은 tsdoc/syntax가 단독 담당 ──
+  'jsdoc/check-tag-names': 'off',
+  // 완전한 문장을 위해 작성하는건대 한글 하고는 잘 안 맞음
+  'jsdoc/require-description-complete-sentence': 'off',
+  // ── 과함: 파일마다 @file 헤더 강제 ──
+  'jsdoc/require-file-overview': 'off',
+  // ── 작동에 옵션이 필수인데 정책이 없어 "검사 0건 + 설정오류만" 출력하는 룰 ──
+  'jsdoc/no-missing-syntax': 'off', // tsdoc 따름
+  'jsdoc/no-restricted-syntax': 'off', // tsdoc 따름
+  'jsdoc/require-tags': 'off', // tags 옵션 필요
+  'jsdoc/match-name': 'off', // match 옵션 필요
+  'jsdoc/match-description': 'off',
+  'jsdoc/text-escaping': 'off', // escapeHTML/escapeMarkdown 옵션 필요
+  // ── ESLint 9에서 작동 불가: 플러그인이 직접 "이 룰 끄고 processor 쓰라"고 출력 ──
+  'jsdoc/check-examples': 'off',
+  'jsdoc/require-template': 'off',
+  'jsdoc/require-example': 'off',
+}
+
+export function docs({ files = ['**/src/**/*.{ts,tsx}'] } = {}) {
+  return [
+    {
+      name: '@3o3/eslint-config/docs',
+      files,
+      ignores: [
+        '**/*.{test,spec}.{ts,tsx}',
+        '**/*.stories.{ts,tsx}',
+        '**/*.d.ts',
+        '**/_internal/**',
+      ],
+      plugins: { jsdoc, tsdoc },
+      settings: {
+        jsdoc: {
+          mode: 'typescript',
+          // TSDoc 표준은 제네릭 문서화에 @typeParam을 쓴다(@template 아님).
+          tagNamePreference: { template: 'typeParam' },
+        },
+      },
+      rules: {
+        ...disabledJsdocRules,
+        'jsdoc/informative-docs': 'off',
+
+        'jsdoc/require-jsdoc': [
+          'error',
+          {
+            publicOnly: true,
+            enableFixer: false,
+            require: { FunctionDeclaration: false },
+            contexts: [
+              'ExportNamedDeclaration > FunctionDeclaration', // export function
+              'ExportNamedDeclaration > VariableDeclaration > VariableDeclarator > ArrowFunctionExpression', // export const () =>
+              'ExportNamedDeclaration > TSInterfaceDeclaration', // export interface
+            ],
+          },
+        ],
+      },
+    },
+  ]
+}
+
+export default docs

package/src/index.js

@@ -0,0 +1,49 @@
+import base from './base.js'
+import reactLayer from './react.js'
+import all from './all.js'
+import { docs } from './docs.js'
+import eslintConfigPrettier from 'eslint-config-prettier'
+
+/**
+ * `@3o3/eslint-config` — 사용처별 레이어를 골라 쓰는 공유 ESLint 설정(ESLint 9 flat).
+ *
+ * 두 가지 소비 방식을 모두 지원한다.
+ *
+ * 1) 배열 스프레드(named export):
+ * ```js
+ * import { base, react } from '@3o3/eslint-config'
+ * export default [...base, ...react]
+ * ```
+ *
+ * 2) ESLint 가 권장하는 `extends` 스타일(default export + `defineConfig`):
+ * ```js
+ * import { defineConfig } from 'eslint/config'
+ * import threeo3 from '@3o3/eslint-config'
+ * export default defineConfig([
+ *   { plugins: { '@3o3': threeo3 }, extends: ['@3o3/base', '@3o3/react'] },
+ * ])
+ * ```
+ *
+ * default export 는 `configs` 맵을 가진 플러그인 형태(typescript-eslint /
+ * eslint-plugin-react 와 동일한 패턴)라 `extends: ['@3o3/<layer>']` 문자열로
+ * 참조된다. `<layer>` 는 base / react / all.
+ */
+const plugin = {
+  meta: { name: '@3o3/eslint-config' },
+  // `extends: ['@3o3/<layer>']` 문자열 참조용(typescript-eslint / react 패턴).
+  configs: {
+    base,
+    react: reactLayer,
+    all,
+  },
+  docs,
+  prettier: eslintConfigPrettier,
+}
+
+export default plugin
+
+// 배열 스프레드용 named export (기존 방식 유지)
+export { base, all }
+export { reactLayer as react }
+export { docs }
+export { eslintConfigPrettier as prettier }

package/src/react.js

@@ -0,0 +1,52 @@
+import tseslint from 'typescript-eslint'
+import react from 'eslint-plugin-react'
+import reactHooks from 'eslint-plugin-react-hooks'
+import * as emotionPlugin from '@emotion/eslint-plugin'
+
+/**
+ * react 레이어 — base 위에 얹는 React 델타.
+ *
+ * eslint-plugin-react(flat recommended) + react-hooks(rules-of-hooks / exhaustive-deps)
+ * + @emotion 을 포함한다. base 를 먼저 스프레드한 뒤 이 레이어를 스프레드한다.
+ *
+ * react-hooks v7 의 flat preset(recommended-latest)은 React Compiler 시대의
+ * 16개 규칙 슈퍼셋이라 기존 동작과 크게 달라진다. 따라서 preset을 쓰지 않고
+ * 플러그인만 등록한 뒤 기존에 켜져 있던 두 규칙만 명시적으로 활성화한다.
+ *
+ * @example
+ * ```js
+ * import { base, react } from '@3o3/eslint-config'
+ * export default [...base, ...react]
+ * ```
+ */
+const reactLayer = tseslint.config({
+  files: ['**/*.{ts,tsx}'],
+  extends: [react.configs.flat.recommended],
+  languageOptions: {
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+  settings: {
+    react: { version: 'detect' },
+  },
+  plugins: {
+    // @emotion/eslint-plugin 11.x는 flat preset이 없어 수동으로 등록한다.
+    '@emotion': emotionPlugin,
+    'react-hooks': reactHooks,
+  },
+  rules: {
+    '@emotion/pkg-renaming': 'error',
+
+    'react/prop-types': 'off',
+    // React.memo, React.forwardRef에서 사용하는 경우도 막고 있어서
+    'react/display-name': 'off',
+    // 기존 v4 recommended preset에서 켜져 있던 규칙 (수동 등록 시 명시 필요)
+    'react-hooks/rules-of-hooks': 'error',
+    'react-hooks/exhaustive-deps': 'error',
+    'react/react-in-jsx-scope': 'off',
+    'react/no-unknown-property': ['error', { ignore: ['css'] }],
+  },
+})
+
+export default reactLayer