freelang-v4 4.3.0

package/docs/README.md

@@ -0,0 +1,175 @@
+# 🌍 FreeLang v4
+
+**AI-First 프로그래밍 언어**
+
+> 완전한 구현 + 성능 중심 + 확장성 높음
+
+---
+
+## 🎯 소개
+
+FreeLang v4는 **정적 타입 프로그래밍 언어**로서 다음을 제공합니다:
+
+- ✅ **완전한 구현**: Lexer → Parser → Compiler → VM
+- ✅ **AI-First 설계**: LLM 통합 기반 언어
+- ✅ **성능 중심**: 병렬 처리, 메모리 최적화
+- ✅ **프로덕션 준비**: 82.6% 완성도, 95.4% 테스트 통과
+
+---
+
+## 📚 문서
+
+| 문서 | 설명 |
+|------|------|
+| 📖 [**학습 가이드**](learning-guide.md) | 10단계 커리큘럼 (초급→고급) |
+| 📚 [**API 레퍼런스**](api-reference.md) | 42개 표준 라이브러리 함수 |
+| 🌍 [**언어 비교**](comparison.md) | Python, JavaScript, Go, Rust와 비교 |
+| 📊 [**완성도 평가**](language-completeness.md) | 82.6% 종합 평가 |
+| 📈 [**성능 벤치마크**](benchmarks.md) | 4,420 ops 측정 결과 |
+| 🏗️ [**아키텍처**](architecture.md) | 시스템 설계 및 구현 |
+
+---
+
+## 🚀 빠른 시작
+
+### 설치
+
+```bash
+git clone https://github.com/kimjindol2025/freelang-langv4.git
+cd freelang-langv4
+npm install && npm run build
+```
+
+### 첫 번째 프로그램
+
+```freelang
+let message = "Hello, FreeLang!"
+println(message)
+
+let numbers = [1, 2, 3, 4, 5]
+for x in numbers {
+  println(str(x * x))
+}
+```
+
+### 실행
+
+```bash
+node dist/vm.js hello.fl
+```
+
+---
+
+## 💡 주요 특징
+
+### 1. 정적 타입 시스템
+```freelang
+let name: str = "Alice"
+let age: i32 = 30
+let scores: [i32] = [85, 90, 95]
+```
+
+### 2. 함수형 프로그래밍
+```freelang
+let doubled = numbers.fold([], fn(acc, x) -> {
+  acc.push(x * 2)
+  acc
+})
+```
+
+### 3. 에러 처리
+```freelang
+match parse_int("42") {
+  case Ok(num) -> println(str(num)),
+  case Err(e) -> println(e)
+}
+```
+
+### 4. 병렬 처리 & 분산 시스템
+```freelang
+let pool = worker_pool_new(4)
+worker_pool_process(pool, task)
+```
+
+---
+
+## 📊 성능 벤치마크
+
+```
+문자열 처리:      2,200 ops ⚡
+컬렉션:            700 ops ⚡
+수학 연산:         300 ops ⚡⚡⚡
+함수 호출:          20 ops ✅
+에러 처리:         300 ops ✅
+구조체:            300 ops ✅
+캐시 연산:         300 ops ✨ (신규)
+메모리 할당:       300 ops ✨ (신규)
+───────────────────────────────
+합계:            4,420 ops (15.7% 개선)
+```
+
+---
+
+## 🎓 학습 경로
+
+| 단계 | 주제 | 시간 |
+|------|------|------|
+| 1-4 | **초급** (변수, 함수, 배열, 에러) | 8h |
+| 5-7 | **중급** (함수형, 모듈, 메모리) | 6h |
+| 8-10 | **고급** (병렬, 분산, 프로젝트) | 6h |
+
+👉 [**10단계 학습 가이드 시작하기**](learning-guide.md)
+
+---
+
+## 🔧 기술 스택
+
+- **언어**: FreeLang v4
+- **컴파일러**: TypeScript (src/)
+- **런타임**: Node.js VM
+- **테스트**: Jest (95.4% 통과)
+- **배포**: GitHub Pages + Gogs
+
+---
+
+## 📈 프로젝트 상태
+
+```
+Phase 1-3:  ✅ 완료  기초 구현
+Phase 4-6:  ✅ 완료  성능 & 분산
+Phase 7+:   🔄 진행중 고급 기능
+```
+
+| 메트릭 | 수치 |
+|--------|------|
+| **완성도** | 82.6% |
+| **테스트** | 251/263 (95.4%) |
+| **코드 라인** | 4,958줄 |
+| **표준 함수** | 42개 |
+
+---
+
+## 🔗 링크
+
+- 🐙 **GitHub**: https://github.com/kimjindol2025/freelang-langv4
+- 📦 **Gogs**: https://gogs.dclub.kr/kim/freelang-v4
+- 📖 **문서**: 이 페이지의 문서 섹션 참고
+
+---
+
+## 💬 피드백 & 기여
+
+- 🐛 [버그 리포트](https://github.com/kimjindol2025/freelang-langv4/issues)
+- 💡 [기능 제안](https://github.com/kimjindol2025/freelang-langv4/discussions)
+
+---
+
+## 📄 라이선스
+
+MIT License - 자유롭게 사용하세요!
+
+---
+
+**Happy Coding! 🚀**
+
+Last Updated: 2026-04-05

package/docs/V1_V2_V3_ANALYSIS.md

@@ -0,0 +1,107 @@
+# FreeLang v1/v2/v3 실패 분석 → v4 교훈
+
+## 수치 비교
+
+| 항목 | v1 | v2 | v3 | v4 |
+|------|-----|-----|-----|-----|
+| 소스 파일 | 304 | 344 | 94 | 11 |
+| 소스 LOC | 109,515 | 115,628 | 34,905 | 5,764 |
+| 커밋 | 406 | 402 | 73 | 21 |
+| Phase | 25 | 24 | 9 | 6 |
+| 폴더 (src/) | 32 | 55 | 1 (flat) | 1 |
+| 테스트 결과 | 140 실패 | OOM Killed | 9 통과 | **0 실패 (334)** |
+| 파서 개수 | 1 (split) | 6 | 1 | 1 (699줄) |
+| 디스크 | 317 MB | ~300 MB | ~5 MB | ~1 MB |
+
+## v1 실패 원인
+
+### 1. 컴파일러가 5개 (어느 것도 미완성)
+- `src/compiler/` — SimpleParser + CGenerator (토이 수준)
+- `src/parser/` — 2,132줄 (별도)
+- `src/vm/` — compiler.ts + vm.ts (별도)
+- `src/interpreter/` — 2,887줄 (별도)
+- `src/codegen/` — LLVM, C, multi-backend (별도)
+
+파이프라인이 연결 안 됨. 각각 독립적으로 존재.
+
+### 2. 토크나이저가 정규식 split
+```typescript
+// v1: 공백 포함 문자열 깨짐, 2글자 연산자 미처리
+const parts = trimmed.replace(/([(){}\[\];:,])/g, ' $1 ').split(/\s+/);
+```
+
+### 3. stdlib 159개 파일이 전부 TypeScript 래퍼
+```typescript
+// FreeLang 코드에서 호출 경로 없음
+static abs(x: number): number { return globalThis.Math.abs(x); }
+```
+
+### 4. Phase 10에서 v1.0.0 선언 후 Phase 25까지 무한 확장
+Swagger, ORM, MongoDB, gRPC, WebSocket, CI/CD... 마지막 커밋이 Phase 25 Revert.
+
+### 5. 테스트 10.5% 실패 (140/1,338), 6분 40초 소요
+
+## v2 실패 원인
+
+### 1. v1보다 폴더 더 늘어남 (32 → 55)
+`type-checker/`, `type-system/`, `types/` 3개 공존. `analyzer/`에 38개 파일.
+
+### 2. 파서 6개 (안 되면 새로 만들기 반복)
+```
+parser.ts           1,397줄
+one-pass-parser.ts    819줄
+partial-parser.ts     675줄
+block-parser.ts       459줄
+async-parser.ts       359줄
+expression-completer  613줄
+합계:               5,279줄
+```
+
+### 3. Phase 폴더가 src/ 안에 16개 혼재
+```
+src/phase-6/ src/phase-8/ src/phase-9/ src/phase-10/ (2.5MB!)
+src/phase-11/ ~ src/phase-24/
+```
+작업 단위와 코드 구조 구분 불가.
+
+### 4. 테스트 OOM Killed (82,386줄 테스트가 메모리 초과로 끝까지 못 돌아감)
+
+## v3 실패 원인
+
+### 1. 규모는 줄었지만 (34,905 LOC) 73커밋에 Phase 9까지 확장
+### 2. CSI (Claude Self-Interrogation) 등 언어 외 기능에 집중
+### 3. "v3.0.0 Release Ready" 선언 후에도 계속 기능 추가
+### 4. 테스트 9개뿐 (커버리지 부족)
+
+## v4가 다르게 한 것
+
+| 문제 | v1/v2/v3 | v4 |
+|------|---------|-----|
+| 설계 | 코드부터 침 | **설계 10 Step 먼저** |
+| 파이프라인 | 분리/중복 | **1개 연결 (Lexer→Parser→Checker→Compiler→VM)** |
+| 범위 | Phase 무한 확장 | **6 Phase로 끝** |
+| 파서 | 여러 개 (안 되면 새로) | **1개 (RD+Pratt, 699줄)** |
+| 폴더 | 32~55개 | **src/ 1개 (11파일)** |
+| 테스트 | 실패/OOM/부족 | **334개 0 실패** |
+| 완성 | 미완성 | **E2E 실행 (factorial, fizzbuzz, fibonacci)** |
+
+## 핵심 교훈
+
+```
+v1: "만들면서 설계하자" → 파이프라인 미연결
+v2: "v1 교훈으로 더 잘 하자" → v1보다 더 비대해짐
+v3: "이번엔 작게 하자" → 그래도 Phase 9까지 확장
+v4: "설계 먼저. 6 Phase. 끝." → 5,764 LOC에 334 tests 0 failures
+```
+
+## v5 참고 자료
+
+- **AST Patterns**: https://gogs.dclub.kr/kim/ast-patterns.git
+  - 8가지 AST 구현 패턴 (Classic Tree, Tagged Union, Flat, Arena, Immutable, Green-Red Tree 등)
+  - v4는 #2 Tagged Union 사용 중
+  - v5 성능 최적화 시 #4 Flat AST 또는 #5 Arena AST 검토
+- **Observability Daemon**: https://gogs.dclub.kr/kim/Observability-Daemon.git
+  - 코드 분석 어시스턴트 (에디터 연동 CLI)
+  - 실시간 위험도 분석 (메모리, 성능, 에러 핸들링)
+  - Vim/Emacs/Sublime/VSCode 통합, CI/CD 파이프라인 지원
+  - v5 FreeLang 코드 분석 도구(linter/advisor) 구현 시 참고

package/docs/_config.yml

@@ -0,0 +1,36 @@
+# GitHub Pages 설정
+title: FreeLang v4 - AI-First 프로그래밍 언어
+description: 완전한 구현, 성능 중심, 확장성 높은 프로그래밍 언어
+author: Kim Jin Dol
+email: contact@freelang.dev
+
+# 테마 설정
+theme: jekyll-theme-minimal
+
+# 기본 설정
+markdown: kramdown
+highlighter: rouge
+
+# 플러그인
+plugins:
+  - jekyll-sitemap
+  - jekyll-seo-tag
+  - jekyll-feed
+
+# SEO 설정
+lang: ko-KR
+locale: ko_KR
+
+# 빌드 설정
+exclude:
+  - .gitignore
+  - README.md
+  - LICENSE
+  - node_modules
+  - EXPERIENCE.md
+  - V1_V2_V3_ANALYSIS.md
+
+# 출력 설정
+output: web
+future: false
+show_downloads: true