mandu-lint

name	mandu-lint
description	Lint 가이드 — 가드레일의 한 축. oxlint 셋업 / 실행 / type-aware / lefthook 통합. "lint 켜줘", "코드 스타일 검사", lint 에러 발생 시 자동 호출.

Mandu Lint

Mandu 의 lint 레이어는 guard (아키텍처) + typecheck (타입) + lint (코드 품질) 3축 가드레일 중 하나. oxlint (Rust-based, ESLint 대비 50–100× 빠름) 를 기본으로.

가드레일 체계 (꼭 기억할 것)

레이어	도구	무엇을 잡나	비용
guard	mandu guard / mandu_guard_check	아키텍처 / 레이어 / import 규칙	~1s
typecheck	mandu check / tsgo	타입 에러	~7s
lint	oxlint / mandu.lint	코드 품질 (no-explicit-any, no-unused-vars, 등)	~500ms
lint --type-aware	oxlint --type-aware / mandu guard --type-aware	타입 의존 lint (no-floating-promises)	~3s

세 개 모두 녹색이 된 후에만 commit / push. mandu check 는 이 모두를 종합 실행.

Trigger

• 파일 편집 후 (특히 대량 수정 / 리팩터)
• "lint 해줘", "코드 스타일 체크", "warning 줄여줘"
• lint 에러가 CI 에서 발견된 경우
• 신규 프로젝트 셋업 / 기존 프로젝트에 lint 미설치 상태

MCP 도구

도구	용도	side effect
mandu.lint	린트 실행 + 에러/경고 카운트	없음 (읽기 전용)
mandu.lint.setup	oxlint 설치 + .oxlintrc.json 스캐폴드 + scripts 배선	파일 수정 (destructive)

표준 흐름

1. 신규 프로젝트

mandu init 은 .oxlintrc.json + oxlint devDep + lint 스크립트 + lefthook.yml (pre-push lint + typecheck) 를 기본 포함. 추가 작업 불필요.

2. 기존 프로젝트에 lint 가 없는 경우

mandu.lint.setup({ dryRun: true })   ← 먼저 계획 보기
  → mandu.lint.setup({})              ← 적용
  → mandu.lint({})                    ← 베이스라인 확인

또는 shell:

mandu lint --setup
mandu lint

3. 편집 후 검증

mandu-mcp-verify fast path 에 이미 포함됨:

mandu.ate.auto_pipeline   ← parallel
mandu.guard.check         ← parallel
mandu.lint                ← parallel (신규)
mandu.doctor              ← parallel

4. 자동 수정

절대 oxlint --fix . 를 무차별 실행하지 말 것. 과거에 .toSorted() 변환으로 ES 타겟이 깨진 전례 있음 (docs/tooling/oxc-lint-roadmap.md §"1차 --fix 대참사").

안전한 자동 수정 절차:

1. 한 룰만 활성화한 임시 config 작성:

   cat > .oxlintrc.fix-type-imports.json <<'EOF'
   {
     "categories": { "correctness": "off" },
     "rules": { "typescript/consistent-type-imports": "warn" }
   }
   EOF
   

2. 해당 룰만 --fix:

   oxlint --config .oxlintrc.fix-type-imports.json --fix .
   

3. 즉시 typecheck + 테스트 검증
4. 커밋
5. 임시 config 삭제

5. Type-aware (선택)

bun add -D oxlint-tsgolint
bun x oxlint --type-aware .
# 또는
mandu guard --type-aware

Type-aware 룰이 잡는 것:

• typescript/no-floating-promises — await 누락
• typescript/no-misused-promises — Promise 를 boolean 자리에
• typescript/strict-boolean-expressions — nullish 체크 누락
• typescript/preserve-caught-error — throw new Error("...", { cause }) 누락

표준 .oxlintrc.json (Mandu 템플릿 기준)

{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off",
    "style": "off",
    "perf": "off",
    "restriction": "off",
    "nursery": "off"
  },
  "rules": {
    "typescript/no-explicit-any": "error",
    "typescript/consistent-type-imports": "warn",
    "typescript/no-unused-vars": ["warn", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
    "no-debugger": "error"
  },
  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/.mandu/**", "**/generated/**"],
  "overrides": [
    {
      "files": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/tests/**"],
      "rules": {
        "typescript/no-explicit-any": "off",
        "typescript/no-unused-vars": "off"
      }
    }
  ]
}

CI 통합

Mandu 신규 프로젝트는 lefthook.yml 포함:

pre-push:
  parallel: true
  commands:
    typecheck:
      run: bun run check
    lint:
      run: bun run lint

prepare: "lefthook install" 스크립트가 bun install 시 자동으로 hook 을 걸음.

mandu build 게이트

프로덕션 빌드 전 lint 에러 는 자동으로 빌드를 막음 (warning 은 통과). 긴급 배포 시 --no-lint 로 우회:

mandu build              # lint error 있으면 block
mandu build --no-lint    # lint 건너뛰기

절대 규칙

#	규칙	이유
L-1	oxlint --fix . 전역 실행 금지	과거 ES 타겟 깨짐. 룰별 selective fix 패턴 사용
L-2	lint 에러를 .oxlintrc.json 의 off 로 돌려 회피 금지	실제 버그 놓침. site-level // oxlint-disable-next-line <rule> 또는 실제 수정
L-3	mandu.lint.setup 은 기존 lint script 를 덮어쓰지 않음	ESLint 사용자 프로젝트 보호
L-4	편집 후 mandu-mcp-verify 없이 commit 금지	lint 는 verify 의 한 축

Anti-patterns

AP-1 — oxlint 룰을 모두 off 로 돌리기

• 증상: 에러가 뜨면 .oxlintrc.json 에 "rule-name": "off" 추가
• 왜 안 되나: 의도적 패턴이면 site-level disable 이 맞고, 실수라면 고쳐야 함. 전역 off 는 같은 실수를 또 만들 여지를 남김
• 대응: (a) 정말 의도적이면 해당 사이트에 // oxlint-disable-next-line <rule> + 이유 주석, (b) 실수면 실제 수정

AP-2 — lint 를 CI 에서만 돌리기

• 증상: 로컬 에서 안 돌리고 CI 에서 처음 실패 발견
• 왜 안 되나: 왕복 5–10분. 에디터 plugin + pre-push hook 으로 로컬에서 5초 안에 확인 가능
• 대응: oxlint-vscode 설치 + lefthook install (템플릿이 이미 제공)

AP-3 — oxlint 와 eslint 동시 실행

• 증상: 기존 ESLint 설정을 남긴 채 oxlint 추가
• 왜 안 되나: 룰 중복 → warning 2배 → 개발자 번아웃
• 대응: mandu-lint 채택 시 .eslintrc.* + ESLint 관련 deps 전부 제거 (docs/tooling/eslint-to-oxlint.md 참고)

Quick Reference

lint 가드레일 하루 주기:
  편집 ─→ 에디터 oxlint plugin 이 즉시 표시
       ─→ mandu-mcp-verify (lint + guard + ate + doctor 병렬)
       ─→ pre-push (lefthook) lint + typecheck
       ─→ CI lint + typecheck + guard
       ─→ mandu build 의 자동 lint 게이트

See Also

• mandu-guard-guide — 아키텍처 가드레일 (lint 와 상호보완)
• mandu-mcp-verify — verify fast path 에 lint 포함
• mandu-mcp-safe-change — 대규모 refactor 의 verify 단계에 lint
• docs/tooling/oxc-lint-roadmap.md — 내부 도입 로드맵
• docs/tooling/eslint-to-oxlint.md — ESLint → oxlint 마이그레이션 가이드