jell-utils 0.0.18 → 0.2.0

package/internal-docs/OBSIDIAN_PROJECT_PROMPT.md

@@ -0,0 +1,302 @@
+# jell-utils.js - Obsidian 프로젝트 문서
+
+## 프로젝트 개요
+
+**프로젝트명**: jell-utils  
+**버전**: 0.1.0  
+**타입**: TypeScript 기반 NPM 패키지  
+**목적**: 개인용 JavaScript/TypeScript 유틸리티 함수 라이브러리  
+**저장소**: https://github.com/jellive/jell-utils.js  
+**NPM**: https://www.npmjs.com/package/jell-utils  
+**라이선스**: MIT  
+**작성자**: Jell <jellive7@gmail.com>
+
+## 프로젝트 상태
+
+- ✅ **배포 상태**: 활성 (npm에 배포됨)
+- ✅ **테스트**: 50개 테스트 케이스, 79.67% 커버리지
+- ✅ **빌드**: TypeScript → JavaScript 컴파일
+- ✅ **품질 관리**: ESLint, Prettier 적용
+- ✅ **CI/CD**: GitHub Actions (semantic-release)
+
+## 핵심 기능 카테고리
+
+### 1. 한국어 관련 기능
+
+- `isKorean(message: string)`: 한글 문자 포함 여부 검사
+- `isBusinessNumber(businessNumber: string)`: 사업자등록번호 유효성 검증 (체크섬 알고리즘)
+- `chosungSearch(str: string, search: string)`: 한글 초성 검색 (예: "ㄱㄴㄷ"로 "가나다" 검색)
+- `getKoreanDate(dateString, isYear)`: 한국식 날짜 포맷 (예: "3월 15일", "2024년 3월 15일")
+
+### 2. 문자열 처리
+
+- `parseTag(txt: string)`: HTML 엔티티 디코딩 (&lt; → <)
+- `toCamelCase(txt: string)`: snake_case → camelCase 변환
+- `toSnakeCase(txt: string)`: 일반 문자열 → snake_case 변환
+- `toTitleCase(txt: string)`: Title Case 변환 (첫 글자 대문자)
+- `toText(txt: string)`: HTML <br> → \n 변환
+- `toHtml(txt: string)`: \n → <br> 변환
+- `clearTag(txt: string, preserveErrorTags)`: XSS 방지하며 HTML 태그 제거
+- `replaceBetween(str, txt, startIndex, endIndex)`: 인덱스 기반 문자열 교체
+- `extractNumbers(str: string)`: 문자열에서 숫자만 추출
+- `maskString(str, visibleStart, visibleEnd, maskChar)`: 민감정보 마스킹 (예: 카드번호)
+- `getFileExtension(filename: string)`: 파일 확장자 추출
+
+### 3. 숫자 및 시간 파싱
+
+- `parseNumber(target: string, defaultValue: number, isFloat)`: 문자열을 숫자로 안전하게 파싱
+- `parseTime(target: string, defaultValue: number)`: 시간 문자열 파싱 (MM:SS, HH:MM:SS)
+
+### 4. 날짜 처리
+
+- `getNowDate()`: 현재 시간을 datetime 포맷으로 반환
+- `formatDate(date)`: yyyy-mm-dd 포맷으로 변환
+- `calDDay(date)`: D-day 계산
+- `dateDiff(date1, date2)`: 두 날짜 차이 계산 (일/시간/분/초 객체 반환)
+
+### 5. 객체 조작
+
+- `clone<T>(obj: T)`: 깊은 복사 (structuredClone 또는 JSON fallback)
+- `getByPath<T>(obj, path, defaultValue)`: 경로 문자열로 중첩 객체 값 가져오기 (예: 'user.profile.name')
+- `setByPath(obj, path, value)`: 경로 문자열로 중첩 객체 값 설정
+- `deepMerge<T>(target, source)`: 객체 깊은 병합
+- `objectToQueryString(obj)`: 객체를 URL 쿼리 스트링으로 변환
+
+### 6. 배열 조작
+
+- `equalArrays(a, b)`: 배열 비교 (얕은 비교)
+- `groupBy<T>(array, key)`: 배열을 특정 키로 그룹화
+- `sortBy<T>(array, key, order)`: 객체 배열 정렬 (asc/desc)
+
+### 7. 비동기 처리
+
+- `retry<T>(fn, maxRetries, delay)`: exponential backoff로 비동기 함수 재시도
+
+### 8. 브라우저 유틸리티
+
+- `isiOS()`: iOS 기기 감지 (User Agent 기반)
+
+## 기술 스택
+
+### 언어 및 런타임
+
+- TypeScript 5.2.2
+- Node.js (ES6+)
+
+### 개발 도구
+
+- **빌드**: TypeScript Compiler (tsc)
+- **테스트**: Jest 29.7.0 + ts-jest
+- **린트**: ESLint + @typescript-eslint
+- **포맷팅**: Prettier
+- **CI/CD**: semantic-release + GitHub Actions
+
+### 의존성 관리
+
+- npm (주)
+- yarn (부)
+
+## 프로젝트 구조
+
+```
+jell-utils.js/
+├── src/
+│   └── index.ts           # 메인 소스 파일 (모든 유틸 함수)
+├── lib/
+│   ├── index.js           # 컴파일된 JavaScript
+│   └── index.d.ts         # TypeScript 타입 정의
+├── __tests__/
+│   ├── korean.test.ts     # 한국어 관련 테스트
+│   ├── string.test.ts     # 문자열 처리 테스트
+│   ├── number.test.ts     # 숫자/시간 파싱 테스트
+│   ├── date.test.ts       # 날짜 처리 테스트
+│   ├── object.test.ts     # 객체 조작 테스트
+│   ├── array.test.ts      # 배열 조작 테스트
+│   └── async.test.ts      # 비동기 처리 테스트
+├── coverage/              # 테스트 커버리지 리포트
+├── .github/workflows/     # GitHub Actions CI/CD
+├── package.json
+├── tsconfig.json
+├── jestconfig.json
+└── .npmrc                 # npm 인증 토큰 (gitignore)
+```
+
+## 개발 워크플로우
+
+### 로컬 개발
+
+```bash
+# 의존성 설치
+npm install
+
+# 빌드
+npm run build
+
+# 테스트
+npm test
+npm run test:coverage
+
+# 린트
+npm run lint
+npm run lint:fix
+
+# 포맷팅
+npm run format
+```
+
+### 배포 프로세스
+
+```bash
+# 1. 변경사항 커밋
+git add .
+git commit -m "feat: new feature description"
+git push
+
+# 2. 버전 업데이트
+npm version patch   # 버그 수정
+npm version minor   # 새 기능
+npm version major   # Breaking changes
+
+# 3. 배포 (자동으로 test + lint + build 실행)
+npm publish
+```
+
+### Git Workflow
+
+- **브랜치**: master (메인 브랜치)
+- **커밋 컨벤션**: Conventional Commits
+  - `feat:` - 새 기능 (MINOR)
+  - `fix:` - 버그 수정 (PATCH)
+  - `docs:` - 문서 변경
+  - `chore:` - 빌드/설정 변경
+  - `BREAKING CHANGE:` - Breaking changes (MAJOR)
+
+## 품질 관리
+
+### 테스트 커버리지
+
+- **Statements**: 79.67%
+- **Branch**: 73.38%
+- **Functions**: 88.88%
+- **Lines**: 82.81%
+- **총 테스트**: 50개 (모두 통과)
+
+### 자동화된 검증
+
+- `prepublishOnly`: 배포 전 test + lint 자동 실행
+- `prepare`: 빌드 전 자동 실행
+- GitHub Actions: PR 및 push 시 CI 자동 실행
+
+## 사용 예시
+
+```typescript
+import util from 'jell-utils'
+
+// 한국어 검증
+util.isKorean('안녕하세요') // true
+util.isBusinessNumber('1018626554') // true
+util.chosungSearch('김철수', 'ㄱㅊㅅ') // true
+
+// 문자열 처리
+util.toCamelCase('hello_world') // 'helloWorld'
+util.maskString('1234567890', 3, 3) // '123****890'
+
+// 객체 조작
+const obj = { user: { profile: { name: 'John' } } }
+util.getByPath(obj, 'user.profile.name') // 'John'
+
+// 배열 처리
+const items = [{ age: 30 }, { age: 25 }, { age: 35 }]
+util.sortBy(items, 'age', 'asc') // age 기준 오름차순 정렬
+
+// 비동기 재시도
+await util.retry(
+  async () => {
+    return await fetchData()
+  },
+  3,
+  1000
+) // 3번 재시도, 1초 간격
+```
+
+## 주요 이정표
+
+### v0.0.x (초기 버전)
+
+- 기본 유틸리티 함수 구현
+- 한국어 관련 기능
+
+### v0.1.0 (2025-10-11) ✨ 현재 버전
+
+- 50개 포괄적인 테스트 케이스 추가
+- 한국어 특화 기능 강화 (사업자등록번호, 초성 검색)
+- 객체/배열 고급 조작 함수 추가
+- 비동기 retry 유틸리티 추가
+- 테스트 커버리지 79.67% 달성
+- ESLint strict 모드 적용 (any 타입 제거)
+- npm 배포 자동화 개선
+
+## 향후 계획
+
+### 단기 (v0.2.0)
+
+- [ ] 추가 한국어 유틸리티 (주민등록번호 검증, 한글 자모 분리 등)
+- [ ] 테스트 커버리지 90% 이상 달성
+- [ ] 브라우저 호환성 테스트 추가
+- [ ] 성능 벤치마크 추가
+
+### 중기 (v0.x.x)
+
+- [ ] Tree-shaking 지원 (개별 함수 import)
+- [ ] 웹 워커 지원
+- [ ] React hooks 버전 제공
+- [ ] 더 많은 날짜/시간 유틸리티
+
+### 장기 (v1.0.0)
+
+- [ ] 안정화 및 API freeze
+- [ ] 완전한 문서화 (JSDoc + 사이트)
+- [ ] 플러그인 시스템
+- [ ] 다국어 지원 확장
+
+## 알려진 이슈
+
+- TypeScript 5.9.2 사용 중 (ESLint는 5.4.0 미만 권장)
+- jest의 ts-jest 경고 (allowJs 설정 관련)
+- Git push 권한 문제 (credential 재설정 필요)
+
+## 참고 문서
+
+- [NPM 배포 가이드](./NPM_DEPLOYMENT_GUIDE.md) - 로컬 전용
+- [GitHub Repository](https://github.com/jellive/jell-utils.js)
+- [NPM Package](https://www.npmjs.com/package/jell-utils)
+- [블로그](https://blog.jell.kr)
+
+## 프로젝트 관리 메타데이터
+
+**프로젝트 타입**: 오픈소스 라이브러리  
+**유지보수 상태**: 활발히 개발 중  
+**기여 가능 여부**: Yes (MIT 라이선스)  
+**주 사용자**: 개인 프로젝트 (공개)  
+**업데이트 주기**: 기능 추가 시 비정기적  
+**최종 업데이트**: 2025-10-11 (v0.1.0 배포)
+
+---
+
+## Obsidian 태그
+
+#project #typescript #npm #utilities #korean #open-source #active #library
+
+## 연관 프로젝트
+
+- (여기에 이 라이브러리를 사용하는 다른 프로젝트 링크 추가)
+
+## 노트
+
+- 이 라이브러리는 개인 프로젝트에서 자주 사용하는 패턴들을 모아놓은 것
+- 한국어 특화 기능이 강점
+- TypeScript로 작성되어 타입 안정성 보장
+- 테스트 커버리지가 높아 안정적
+
+
+

package/internal-docs/TEST_RESULTS.md

@@ -0,0 +1,153 @@
+# 🧪 CI/CD Pipeline Test Results
+
+## 📊 Test Summary
+
+**전체 테스트 완료**: 2024-01-XX
+**테스트 환경**: 로컬 + GitHub Actions 시뮬레이션
+**안전성**: ✅ 실제 배포 방지됨 (NPM_TOKEN 미설정)
+
+---
+
+## ✅ 성공한 테스트들
+
+### 1. **Semantic Release 설정** ✅
+- **상태**: 완전 작동
+- **검증 결과**: 
+  - 모든 플러그인 로드됨 
+  - Conventional commit 인식됨
+  - BREAKING CHANGE → Major 버전 증가 예정 (0.0.18 → 1.0.0)
+  - 브랜치 필터링 정상 작동 (reboot 브랜치에서 배포 차단됨)
+
+### 2. **Git Hooks (Husky)** ✅  
+- **상태**: 완전 작동
+- **검증 결과**:
+  - Pre-commit: 린트 및 포맷팅 자동 실행 ✅
+  - Commit-msg: Conventional commits 검증 ✅  
+  - Lint-staged: 변경된 파일만 처리 ✅
+
+### 3. **Build & Test Pipeline** ✅
+- **상태**: 완전 작동
+- **검증 결과**:
+  - TypeScript 빌드 성공 ✅
+  - Jest 테스트 통과 ✅ (5/5 tests)
+  - ESLint 통과 ✅
+  - 의존성 설치 성공 ✅
+
+### 4. **GitHub Actions 워크플로우** ✅
+- **상태**: 문법 검증 완료
+- **파일 구조**:
+  - `ci.yml`: Multi-Node.js, Cross-platform 테스트
+  - `release.yml`: Semantic release + NPM 배포
+  - 워크플로우 연결: CI 성공 → Release 실행
+
+### 5. **Conventional Commits** ✅
+- **테스트 커밋**: `feat: implement modern CI/CD pipeline`
+- **BREAKING CHANGE**: 포함됨
+- **예상 버전**: 0.0.18 → 1.0.0
+
+### 6. **안전성 검증** ✅
+- NPM_TOKEN 미설정으로 실제 배포 차단 확인
+- 브랜치 필터링으로 테스트 브랜치에서 배포 차단 확인
+
+---
+
+## ⚠️ 테스트 제한사항
+
+### 1. **GitHub Push 권한**
+- **상태**: 권한 없음 (예상됨)
+- **원인**: `hgyoo-azflow` → `jellive/jell-utils.js` 권한 없음
+- **해결**: 프로젝트 소유자가 직접 push 필요
+
+### 2. **실제 NPM 배포**  
+- **상태**: 테스트 안함 (의도적)
+- **원인**: NPM_TOKEN 미설정
+- **해결**: Repository secrets에 NPM_TOKEN 설정 후 테스트
+
+---
+
+## 🚀 실제 운영을 위한 다음 단계
+
+### **Step 1: Repository Secrets 설정**
+GitHub Repository → Settings → Secrets and variables → Actions:
+
+```bash
+# NPM 배포 토큰 (필수)
+NPM_TOKEN=npm_xxxxxxxxxxxxxxxx
+
+# 선택사항
+SLACK_WEBHOOK_URL=https://hooks.slack.com/...
+CODECOV_TOKEN=xxxxxxxx-xxxx-xxxx...
+```
+
+### **Step 2: Branch Protection Rules** 
+Repository → Settings → Branches → Add rule:
+- Branch name pattern: `main` 
+- ✅ Require pull request before merging
+- ✅ Require status checks to pass
+
+### **Step 3: 실제 배포 테스트**
+```bash
+# 1. 작은 변경사항 커밋
+git checkout -b test/ci-cd-validation
+echo "# CI/CD Test" > TEST.md
+git add TEST.md
+git commit -m "docs: add CI/CD validation test"
+
+# 2. PR 생성 및 merge
+git push origin test/ci-cd-validation
+# GitHub에서 PR 생성 → CI 실행 확인 → Merge
+
+# 3. 자동 배포 확인  
+# GitHub Actions에서 release 워크플로우 실행
+# NPM에 새 버전 자동 배포
+# GitHub Release 자동 생성
+```
+
+---
+
+## 🎯 예상 결과
+
+### **실제 배포시 workflow:**
+1. **CI Pipeline**: ✅ 다중 환경 테스트 (Ubuntu/Windows/macOS, Node 18/20/21)
+2. **Security Scan**: ✅ 의존성 취약점 검사  
+3. **Semantic Analysis**: ✅ 커밋 분석 → 버전 계산 (1.0.0)
+4. **Automated Release**: ✅ GitHub Release + Changelog 생성
+5. **NPM Publish**: ✅ npm registry 배포
+6. **Notifications**: ✅ Slack 알림 (설정시)
+
+### **버전 관리:**
+- **Current**: 0.0.18
+- **Next Release**: 1.0.0 (BREAKING CHANGE 감지)
+- **Changelog**: 자동 생성
+- **Git Tags**: 자동 생성
+
+---
+
+## 📋 Test Checklist
+
+- [x] Semantic Release 설정 및 검증
+- [x] Conventional Commits 형식 검증  
+- [x] Git Hooks 작동 확인
+- [x] Build Pipeline 검증
+- [x] GitHub Actions YAML 문법 확인
+- [x] 안전성 검증 (실제 배포 차단)
+- [ ] 실제 GitHub Push (권한 필요)
+- [ ] NPM Token 설정 후 배포 테스트
+- [ ] Slack 알림 테스트
+
+---
+
+## 🎉 결론
+
+**✅ CI/CD 파이프라인이 완전히 준비되었습니다!**
+
+모든 핵심 기능들이 로컬에서 검증되었으며, 실제 배포를 위해서는:
+1. GitHub Repository 접근 권한 확보
+2. NPM_TOKEN 설정  
+3. Branch protection rules 적용
+
+이후 단순히 `main` 브랜치에 conventional commit으로 merge하기만 하면 **완전 자동화된 버전 관리 + NPM 배포**가 실행됩니다.
+
+---
+
+*테스트 완료 시점: $(date)*

package/internal-docs/TEST_SIMULATION.md

@@ -0,0 +1,27 @@
+# 🧪 CI/CD Pipeline Test Simulation
+
+## Test Environment
+
+- Branch: reboot (safe for testing)
+- Date: $(date)
+- Purpose: Validate CI/CD pipeline without actual deployment
+
+## Test Results
+
+### ✅ Configuration Validation
+
+- Semantic Release: LOADED
+- All Plugins: CONFIGURED
+- Dependencies: INSTALLED
+
+### 🔄 Next Steps
+
+1. Create test commit with conventional format
+2. Run semantic-release dry-run
+3. Validate version calculation
+4. Test GitHub Actions workflow syntax
+
+---
+
+_This is a test file for CI/CD pipeline validation_
+Test change