@3o3/eslint-config 0.2.0 → 1.1.0

package/README.md

@@ -22,6 +22,8 @@ eslint-plugin-react, react-hooks, import, @emotion, jsdoc, tsdoc, prettier)은
 | `all` | `base + react + prettier` 번들 | "전부 켜기" |
 | `prettier` | `eslint-config-prettier`(포매팅 충돌 규칙 off) | 항상 **마지막**에 스프레드 |
 
+`base` 는 자체 규칙 `@3o3/no-app-event-on-window`(error)를 켠다. 앱 이벤트(`flutter_*`)를 `window.addEventListener`·`removeEventListener` 에 문자열 리터럴로 직접 넘기는 코드를 막는다. `onBackPressed` 같은 등록형 이벤트는 직접 붙이면 앱에 등록되지 않아 동작하지 않으므로, 앱 이벤트 전체를 `@3o3/app-bridge` 의 `webView` 로 모은다. `eslint --fix` 가 `webView.addEventListener`·`removeEventListener` 로 바꾸고 import 를 채운다. `webView` 라는 이름을 이미 다른 값에 쓰는 파일은 알리기만 한다.
+
 `react` 는 `base` 위에 얹는 누적 델타다. 각 영역의 3o3 규칙을 이미 포함한다.
 전역 무시(dist/esm/비 ts·tsx)와 프로젝트 고유 규칙은 소비하는 쪽 config 에서 직접 둔다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3o3/eslint-config",
-  "version": "0.2.0",
+  "version": "1.1.0",
   "description": "3o3 공유 ESLint 설정 — 사용처에 따라 레이어(base/react/docs/all)를 골라 쓴다.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "src"
+    "src",
+    "!src/**/__tests__"
   ],
   "repository": {
     "type": "git",
@@ -35,6 +36,12 @@
     "globals": "^15.15.0",
     "typescript-eslint": "^8.60.0"
   },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "typescript": "5.9.3",
+    "vitest": "4.1.9",
+    "@3o3/test-config": "0.1.0"
+  },
   "peerDependencies": {
     "eslint": ">=9",
     "typescript": ">=5"
@@ -46,5 +53,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/base.js

@@ -2,6 +2,7 @@ import js from '@eslint/js'
 import tseslint from 'typescript-eslint'
 import importPlugin from 'eslint-plugin-import'
 import globals from 'globals'
+import plugin from './plugin.js'
 
 /**
  * base 레이어 — js + ts 공통.
@@ -33,7 +34,7 @@ const base = tseslint.config({
     globals: {
       ...globals.node,
       ...globals.browser,
-      ...globals.jest,
+      ...globals.vitest,
       ...globals.es2021,
     },
     parserOptions: {
@@ -43,6 +44,7 @@ const base = tseslint.config({
   settings: {
     'import/resolver': { typescript: {} },
   },
+  plugins: { '@3o3': plugin },
   rules: {
     'no-implicit-coercion': 'error',
     'no-warning-comments': [
@@ -54,6 +56,8 @@ const base = tseslint.config({
     ],
     curly: ['error', 'all'],
     eqeqeq: ['error', 'always', { null: 'ignore' }],
+    // window 에 직접 붙인 등록형 앱 이벤트는 앱에 등록되지 않는다
+    '@3o3/no-app-event-on-window': 'error',
 
     // eslint-plugin-import recommended preset에서 신규 적용 — 기존 config는 import 규칙을 켜지 않았으므로 동작 보존 위해 off
     // (import/export는 TS type re-export에 대한 오탐, 실제 중복 export는 tsc typecheck가 잡음)

package/src/docs.js

@@ -28,7 +28,6 @@ const disabledJsdocRules = {
   // ── ESLint 9에서 작동 불가: 플러그인이 직접 "이 룰 끄고 processor 쓰라"고 출력 ──
   'jsdoc/check-examples': 'off',
   'jsdoc/require-template': 'off',
-  'jsdoc/require-example': 'off',
 }
 
 export function docs({ files = ['**/src/**/*.{ts,tsx}'] } = {}) {
@@ -53,7 +52,16 @@ export function docs({ files = ['**/src/**/*.{ts,tsx}'] } = {}) {
       rules: {
         ...disabledJsdocRules,
         'jsdoc/informative-docs': 'off',
-
+        'jsdoc/require-example': [
+          'error',
+          {
+            enableFixer: false,
+            contexts: [
+              'ExportNamedDeclaration > FunctionDeclaration',
+              'ExportNamedDeclaration > VariableDeclaration > VariableDeclarator > ArrowFunctionExpression',
+            ],
+          },
+        ],
         'jsdoc/require-jsdoc': [
           'error',
           {

package/src/index.js

@@ -1,49 +1,26 @@
 import base from './base.js'
 import reactLayer from './react.js'
+import testsLayer from './tests.js'
 import all from './all.js'
 import { docs } from './docs.js'
 import eslintConfigPrettier from 'eslint-config-prettier'
+import plugin from './plugin.js'
 
-/**
- * `@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,
-}
+// base 와 plugin 이 서로를 참조하므로 레이어는 여기서 채운다.
+// docs·prettier 도 여기서 붙여, base 만 가져오는 소비처가 문서용 플러그인까지 불러오지 않게 한다
+Object.assign(plugin.configs, {
+  base,
+  react: reactLayer,
+  tests: testsLayer,
+  all,
+})
+Object.assign(plugin, { docs, prettier: eslintConfigPrettier })
 
 export default plugin
 
 // 배열 스프레드용 named export (기존 방식 유지)
 export { base, all }
 export { reactLayer as react }
+export { testsLayer as tests }
 export { docs }
 export { eslintConfigPrettier as prettier }

package/src/plugin.js

@@ -0,0 +1,37 @@
+import noAppEventOnWindow from './rules/no-app-event-on-window.js'
+
+/**
+ * `@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 / tests / all.
+ *
+ * base 가 이 객체를 `@3o3` 로 등록한다. 소비처가 다시 등록해도 같은 객체라 중복 정의가 아니다.
+ */
+const plugin = {
+  meta: { name: '@3o3/eslint-config' },
+  rules: {
+    'no-app-event-on-window': noAppEventOnWindow,
+  },
+  configs: {},
+}
+
+export default plugin

package/src/rules/no-app-event-on-window.js

@@ -0,0 +1,123 @@
+const APP_EVENT_PREFIX = 'flutter_'
+const WINDOW_NAMES = ['window', 'globalThis', 'self']
+const METHODS = ['addEventListener', 'removeEventListener']
+const APP_BRIDGE = '@3o3/app-bridge'
+
+const findVariable = (scope, name) => {
+  for (let current = scope; current; current = current.upper) {
+    const variable = current.set.get(name)
+    if (variable) {
+      return variable
+    }
+  }
+  return undefined
+}
+
+/**
+ * 앱 이벤트(flutter_*)를 window 에 직접 붙이는 코드를 막는다. 이벤트 이름이 문자열 리터럴인 호출만 잡는다.
+ * 등록형 이벤트(onBackPressed)는 window 에 직접 붙이면 앱에 등록되지 않는다.
+ */
+const rule = {
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    docs: {
+      description:
+        '앱 이벤트(flutter_*)는 window 대신 @3o3/app-bridge 의 webView 로 구독한다',
+    },
+    schema: [],
+    messages: {
+      useWebView:
+        "앱 이벤트 '{{event}}' 는 window 에 직접 붙이지 말고 @3o3/app-bridge 의 webView.{{method}} 를 쓰세요. 등록형 이벤트는 직접 붙이면 앱에 등록되지 않습니다.",
+    },
+  },
+  create(context) {
+    const { sourceCode } = context
+
+    return {
+      CallExpression(node) {
+        const { callee } = node
+        const [eventName] = node.arguments
+        if (
+          callee.type !== 'MemberExpression' ||
+          callee.computed ||
+          callee.object.type !== 'Identifier' ||
+          !WINDOW_NAMES.includes(callee.object.name) ||
+          callee.property.type !== 'Identifier' ||
+          !METHODS.includes(callee.property.name) ||
+          eventName?.type !== 'Literal' ||
+          typeof eventName.value !== 'string' ||
+          !eventName.value.startsWith(APP_EVENT_PREFIX)
+        ) {
+          return
+        }
+
+        const program = sourceCode.ast
+        const appBridgeImports = program.body.filter(
+          (statement) =>
+            statement.type === 'ImportDeclaration' &&
+            statement.source.value === APP_BRIDGE &&
+            statement.importKind !== 'type'
+        )
+        const webViewSpecifier = appBridgeImports
+          .flatMap((declaration) => declaration.specifiers)
+          .find(
+            (specifier) =>
+              specifier.type === 'ImportSpecifier' &&
+              specifier.imported.name === 'webView' &&
+              specifier.importKind !== 'type'
+          )
+        const localName = webViewSpecifier?.local.name ?? 'webView'
+
+        // webView 가 다른 값을 가리키면 고치지 않는다
+        const variable = findVariable(sourceCode.getScope(node), localName)
+        const canFix = webViewSpecifier
+          ? variable?.defs[0]?.node === webViewSpecifier
+          : !variable
+
+        const importFixes = (fixer) => {
+          if (webViewSpecifier) {
+            return []
+          }
+
+          const namedImport = appBridgeImports.find((declaration) =>
+            declaration.specifiers.some(
+              (specifier) => specifier.type === 'ImportSpecifier'
+            )
+          )
+          if (namedImport) {
+            return [
+              fixer.insertTextAfter(namedImport.specifiers.at(-1), ', webView'),
+            ]
+          }
+
+          // 'use client' 같은 지시어는 맨 위에 남아야 한다
+          const anchor =
+            program.body.find(
+              (statement) => statement.type === 'ImportDeclaration'
+            ) ?? program.body.find((statement) => !statement.directive)
+          return [
+            fixer.insertTextBefore(
+              anchor,
+              `import { webView } from '${APP_BRIDGE}'\n`
+            ),
+          ]
+        }
+
+        context.report({
+          node,
+          messageId: 'useWebView',
+          data: { event: eventName.value, method: callee.property.name },
+          fix: canFix
+            ? (fixer) => [
+                fixer.replaceText(callee.object, localName),
+                ...importFixes(fixer),
+              ]
+            : null,
+        })
+      },
+    }
+  },
+}
+
+export default rule

package/src/tests.js

@@ -0,0 +1,30 @@
+import tseslint from 'typescript-eslint'
+
+/**
+ * tests 레이어 — 테스트 파일에만 적용하는 완화 규칙.
+ *
+ * 대상: `**\/__tests__/**\/*.{ts,tsx}` 와 `**\/*.spec.{ts,tsx}` (레포 테스트 컨벤션).
+ *
+ * 테스트는 목·스텁·DOM 노드 접근 때문에 non-null 어설션(`!`)을 자연스럽게 쓰고,
+ * 임시 픽스처 배열 타입도 `T[]` 로 두는 편이 읽기 쉽다. 프로덕션 코드에는
+ * `no-non-null-assertion`(warn)·`array-type`(array-simple) 을 유지하되, 테스트
+ * 파일에서는 off 한다. base/react 레이어 뒤에 스프레드해야 오버라이드가 적용된다.
+ *
+ * @example
+ * ```js
+ * import { defineConfig } from 'eslint/config'
+ * import threeo3 from '@3o3/eslint-config'
+ * export default defineConfig([
+ *   { plugins: { '@3o3': threeo3 }, extends: ['@3o3/base', '@3o3/react', '@3o3/tests'] },
+ * ])
+ * ```
+ */
+const tests = tseslint.config({
+  files: ['**/__tests__/**/*.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+  rules: {
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/array-type': 'off',
+  },
+})
+
+export default tests