@uiwwsw/hangulscript 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# 0.7.0
+
+- 공식 VS Code 확장 0.2.0: 문법 강조·포맷·진단·타입 정보·정의 이동·스코프 자동 완성·스니펫.
+- 실제 VS Code Extension Host 통합 테스트와 CI 추가.
+- Node 등록 진입점과 CLI에서 상대 경로 .hgs 모듈 직접 실행.
+- 다중 파일 JS·타입 선언 빌드와 .js import 경로 연결.
+- tsconfig compilerOptions·extends 적용과 지원·호환성 계약 문서화.
+
+# 0.7.0-dev.0 (개발 버전)
+
+- VS Code 확장 0.1.0: `.hgs` 문법 강조, 들여쓰기, 문서 포맷, Problems 진단.
+- Vite·CLI·브라우저의 문법·타입 진단에 원본 HGS 위치 표시.
+- 포맷터 API와 확장용 VSIX 빌드 추가.
+
+# 변경 내역
+
+## 0.6.0
+
+문장형이 유일한 기본 문법입니다. 소스는 첫 문장부터 바로 작성합니다.
+
+- **호환되지 않는 변경:** 키워드형 소스 모드·시작 표기·`.ks` 입력을 제거했습니다. 기존 파일은 `.hgs`와 문장형으로 옮겨야 합니다.
+- 모드 감지·전역 키워드 치환·클래스 사후 보정을 제거했습니다.
+- 모듈 가져오기·공개, 비동기·기다리기, 생성기, 예외 처리, 클래스·상속·읽기/쓰기 속성, 자료형·열거값·제네릭을 문장형으로 제공합니다.
+- 잘못된 조건 분기 연결과 반복/함수 밖의 제어 문장을 진단합니다. 문자열·정규식·템플릿·속성 이름을 보존합니다.
+- 기본 함수 15개, 화면 함수 5개, CLI JS+.d.ts, React/Vue Vite 연동을 검증했습니다.
+- 기본 예제의 입력창은 즉시 표시하며 코드는 버튼을 눌렀을 때 실행합니다.
+
+지원 문법과 제약은 [LANGUAGE.md](LANGUAGE.md), React·Vue 연동은 [가이드](docs/frameworks.md)를 참고하세요.

package/LANGUAGE.md

@@ -1,107 +1,172 @@
-# 문장형 HangulScript v0.1 (실험판)
+# 한글스크립트 0.6 문법
 
-`.hgs`를 TypeScript로 변환한다. Python의 들여쓰기·단순한 함수·기본 함수를
-받아들이고, JS의 배열·객체·표현식과 TypeScript 타입을 활용한다.
-Python 소스 호환 언어나 임의의 한국어를 해석하는 AI 실행기가 아니다.
+문장형이 유일한 기본 문법입니다. 시작 표기 없이 첫 문장부터 작성합니다.
+키워드형과 `.ks` 입력은 제거됐습니다. 소스는 `.hgs`, 기본 빌드는 JavaScript와 `.d.ts`입니다.
+문장 블록은 공백 들여쓰기를 사용합니다. 탭과 여러 줄 표현식은 지원하지 않습니다.
+`#`로 시작하는 행은 주석입니다. 행 끝 주석은 지원하지 않습니다.
 
-## 문법
+## 값·함수·조건·반복
 
-파일 첫 줄 `문장으로 시작`으로 문장형을 명시하는 것을 권장한다.
-변수 선언·각 반복·함수 정의 문장으로도 자동 감지한다.
-기존 `.hgs` 키워드형은 계속 지원한다. 같은 파일 안에서는 하나의 방식을 사용한다.
-공백 들여쓰기 폭은 자유지만 같은 블록은 동일해야 하고 탭은 허용하지 않는다.
-`#`는 행 전체 주석이다. 문장 끝 주석은 현재 지원하지 않는다.
-
-```ks
-문장으로 시작
+```text
 이름은 "하늘"이다
-횟수는 3이다
+점수: 숫자는 90이다
+기준은 80으로 고정한다
 
-인사(누구)를 정의한다:
+인사(누구: 문자열)를 정의한다:
     돌려주기 "안녕, " + 누구
 
-각 순서를 범위(횟수)에서:
-    만약 순서 == 0 이라면:
-        출력("처음")
-    아니고 순서 == 1 이라면:
-        출력("다음")
-    아니면:
-        출력(인사(이름))
-
-동안 횟수 > 0:
-    횟수 = 횟수 - 1
-    만약 횟수 == 1 이라면:
+각 수를 범위(3)에서:
+    만약 수 == 1 이라면:
+        계속하기
+    출력(인사(이름), 수)
+
+동안 점수 < 100:
+    점수 = 점수 + 1
+    만약 점수 == 95 이라면:
         멈추기
 ```
 
-- 선언: `이름은 값이다` / `이름는 값이다`. 은·는은 문법적으로 둘 다 허용한다.
-  `let`으로 변환하며 재대입은 `이름 = 값`이다. 같은 범위에서 재선언할 수 없다. 빈 목록은 동적 목록 `any[]`로 생성한다.
-- 함수: `이름(인자)를 정의한다:`. 타입 없는 인자는 `any`로 변환한다.
-  `이름(인자: 문자열)를 정의한다:`처럼 타입을 명시할 수 있다.
-- 반환: `돌려주기 값`; 값 없이도 가능하다.
-- 조건: `만약 식 이라면:` / `아니고 식 이라면:` / `아니면:`.
-- 반복: `각 항목을 목록에서:`; 조사 을·를 모두 허용한다.
-- 조건 반복: `동안 식:`; `멈추기`, `계속하기`를 제공한다.
-- 식: JS의 연산자, 배열, 객체를 사용한다. 참·거짓·비어있음은 기존 변환을 따른다.
-  Python의 `and`, `or`, `in`, 리스트 컴프리헨션, 음수 인덱스는 제공하지 않는다.
+| 기능 | 문장 |
+| --- | --- |
+| 변수 | `이름은 값이다`, 재대입은 `이름 = 값` |
+| 타입 있는 변수 | `점수: 숫자는 90이다` |
+| 고정값 | `기준은 80으로 고정한다` |
+| 함수 | `더함(가: 숫자, 나: 숫자)를 정의한다:` |
+| 반환 | `돌려주기 값`, 값 없이도 가능 |
+| 조건 | `만약 식 이라면:` / `아니고 식 이라면:` / `아니면:` |
+| 반복 | `각 항목을 목록에서:` / `동안 식:` |
+| 반복 제어 | `멈추기` / `계속하기` |
+
+은·는과 을·를은 둘 다 허용합니다. 타입 없는 인자는 `any`, 빈 목록 선언은 `any[]`가 됩니다.
+타입은 `숫자`, `문자열`, `논리`(또는 `불리언`), `모름`, `아무거나`, `무효`를 사용하거나 TypeScript 타입 표현식을 작성할 수 있습니다.
+표현식은 JavaScript 연산자·배열·객체·정규식·템플릿 문자열을 사용합니다.
+`참`, `거짓`, `비어있음`, `정의안됨`은 리터럴입니다. 문자열·주석·속성 이름은 치환하지 않습니다.
+JS 전역 `Math`, `JSON`, `Map`, `Set`, `Date`, `Error` 등은 원래 이름으로 사용합니다.
+임의의 JS/TS 선언·중괄호 블록을 소스로 작성하는 문법은 지원하지 않습니다.
+
+## 선택과 한 번 이상 반복
+
+```text
+상태는 "완료"이다
+상태에 따라:
+    "준비"인 경우:
+        출력("준비 중")
+    "완료"인 경우:
+        출력("끝")
+    그 밖의 경우:
+        출력("알 수 없음")
+
+횟수는 0이다
+먼저 실행한다:
+    횟수 = 횟수 + 1
+횟수 < 3인 동안 반복한다
+```
 
-## 기본 함수
+선택 분기는 다음 분기로 넘어가지 않습니다. `그 밖의 경우:`는 기본 분기입니다.
 
-| 함수 | 의미 |
-| --- | --- |
-| `출력(...값)` | 콘솔 출력 |
-| `길이(문자열 또는 목록)` | UTF-16 코드 단위 또는 항목 수 |
-| `합계(숫자목록)` | 합산 |
-| `정렬(숫자목록)` | 원본을 바꾸지 않고 오름차순 정렬 |
-| `범위(끝)` / `범위(시작, 끝, 간격)` | 끝 제외, 음수 간격 지원, 최대 10만 항목 |
-| `추가(목록, 값)` | 원본 목록에 추가 |
-| `포함(목록, 값)` | 포함 여부 |
-| `나누기(문자열, 구분자)` | 문자열 분리 |
-| `잇기(목록, 구분자)` | 기본 구분자 빈 문자열로 연결 |
+## 모듈
+
+```text
+"./math.js"에서 { 더함 }을 가져온다
+"./settings.js"에서 설정을 가져온다
+
+계산(값: 숫자)를 정의한다:
+    돌려주기 더함(값, 설정.기준)
 
-위 이름은 문장형 파일에 생성하는 기본 함수이므로 사용자 함수·변수 이름으로 쓰지 않는다.
-생성한 TypeScript에는 기본 함수의 구현이 포함된다. 독립 모듈로 사용하려면
-TypeScript 프로젝트의 moduleDetection 설정 또는 export로 모듈 범위를 지정한다.
+계산을 공개한다
+```
+
+여러 이름은 `{ 계산, 더함 }을 공개한다`, 기본 내보내기는 `계산을 기본으로 공개한다`로 작성합니다.
+가져오기·공개 문장은 최상위에서만 사용합니다. CLI는 `.hgs` 모듈 그래프를 묶거나 경로를 바꾸지 않으므로 미리 빌드한 `.js` 경로를 사용합니다.
+React·Vue의 Vite 플러그인은 `.hgs` import를 빌드할 때 처리합니다.
+
+## 비동기·생성기·오류 처리
 
-## 다음 개선 우선순위
+```text
+비동기로 계산(값: 숫자)를 정의한다:
+    결과는 기다리기 Promise.resolve(값 * 2)이다
+    돌려주기 결과
 
-1. **독립 토큰화와 AST**: 현재 행 기반 문장 파서·키워드 치환기를 통합한다.
-   정규식 리터럴, 여러 줄 식, 복잡한 클래스/제네릭 문법은 완전 지원 범위가 아니다.
-2. **원본 위치 진단과 소스맵**: 들여쓰기 오류는 .hgs 행 번호를 표시하지만
-   TypeScript 타입 진단은 현재 확장된 생성 코드 위치를 사용한다.
-3. **표준 라이브러리 계약**: 문자열/목록/사전/날짜를 같은 함수 체계로 확장하고
-   Unicode 문자 수·동등성·정렬·오류 모델을 명시한다.
-4. **VS Code/LSP**: 강조, 자동 완성, 한글 오류 설명, 포맷터를 추가한다.
-5. **웹 프로젝트 통합**: Vite 플러그인과 .hgs 모듈 그래프를 구현한다.
-   현재 CLI는 파일 단위 변환이며 .hgs import 경로를 재작성하지 않는다.
+차례로 목록()를 정의한다:
+    내주기 1
+    내주기 2
 
-문장형은 실험판이다. 웹 데모는 문법 변환·JS 구문 진단만 하며 전체 타입 검사는 하지 않는다.
-DOM과 네트워크가 필요한 결과물은 신뢰하는 로컬 프로젝트에서 생성 TS를 통합해 만든다.
+시도한다:
+    오류를 일으킨다 새 Error("입력을 확인하세요")
+오류를 잡으면:
+    출력(String(오류))
+마지막으로:
+    출력("마침")
+```
+
+`기다리기`는 비동기 함수의 식 맨 앞에 사용합니다. `내주기`는 `차례로` 정의한 함수 안에서 사용합니다.
+브라우저 데모는 네트워크·외부 모듈을 제공하지 않습니다. 모듈과 외부 API 연동은 로컬 프로젝트에서 사용하세요.
+
+## 클래스·자료형·제네릭
+
+```text
+사람 클래스를 정의한다:
+    이름: 문자열은 ""이다
+    생성할 때(이름: 문자열):
+        자신.이름 = 이름
+    소개()를 정의한다:
+        돌려주기 자신.이름
+    별명을 읽으면:
+        돌려주기 자신.이름
+    별명을 바꾸면(값: 문자열):
+        자신.이름 = 값
+
+사람을 이어받아 학생 클래스를 정의한다:
+    생성할 때(이름: 문자열):
+        부모(이름)
+
+사용자는 새 학생("하늘")이다
+출력(사용자.소개())
+
+상자<T> 자료형을 정의한다:
+    값: T
+숫자상자 타입은 상자<숫자>이다
+상태 열거값을 정의한다:
+    준비
+    완료
+복사<T>(값: T)를 정의한다:
+    돌려주기 값
+```
 
-## 0.3 실행·출력과 추가 함수
+자료형·타입 별칭·열거값은 최상위에 작성합니다. 클래스의 추상·접근 제한자·데코레이터 및 전체 TypeScript 문법은 지원 범위가 아닙니다.
 
-CLI의 기본 빌드는 `.js` + `.d.ts`이며 `--typescript`로 기존 TS 출력을 선택한다.
-`ksc run 파일.hgs`는 생성 파일 없이 타입 검사 후 Node.js에서 실행한다.
-JS 출력은 ESM이며, 프로젝트는 `type: module` 또는 ESM 번들러를 사용한다.
-공개 함수에 `내보내기 { 함수이름 }`을 쓰면 해당 타입을 .d.ts로 배포할 수 있다.
+## 기본 함수 15개
 
-추가 기본 함수: `숫자로(값)`, `다듬기(문자열)`, `반올림(값, 자리=0)`,
-`평균(목록)`, `최솟값(목록)`, `최댓값(목록)`.
-평균/최솟값/최댓값의 빈 목록과 숫자로의 빈 문자열·비유한 숫자는 오류다.
-반올림은 JS Math.round 규칙이며 십진 임의 정밀도나 Python round와 같은 규칙을 보장하지 않는다.
+| 함수 | 의미 |
+| --- | --- |
+| `출력(...값)` | 콘솔 출력 |
+| `길이(값)` | 문자열 UTF-16 코드 단위 또는 목록 항목 수 |
+| `추가(목록, 값)` | 원본 목록에 추가 |
+| `포함(목록, 값)` | 포함 여부 |
+| `나누기(글, 구분자)` / `잇기(목록, 구분자)` | 문자열 분리·연결 |
+| `다듬기(글)` | 양 끝 공백 제거 |
+| `숫자로(값)` | 빈 문자열·비유한 숫자는 오류 |
+| `합계(목록)` / `평균(목록)` | 합계·평균, 빈 평균은 오류 |
+| `최솟값(목록)` / `최댓값(목록)` | 빈 목록은 오류 |
+| `반올림(값, 자리=0)` | JS Math.round, 자리 -10~10 |
+| `정렬(목록)` | 원본을 복사해 숫자 오름차순 정렬 |
+| `범위(끝)` / `범위(시작, 끝, 간격)` | 끝 제외, 음수 간격 지원, 최대 10만 항목 |
 
-## 이름과 확장자 이전 (0.4)
+기본 함수 이름은 사용자 선언 이름으로 사용하지 않습니다. JS 부동소수점·반올림 규칙을 따르며 Python 호환·임의 정밀도 십진 연산을 의미하지 않습니다.
 
-제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
-기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
-이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.
+## 화면 함수 5개
 
+`숫자입력("이름", 0)`, `글자입력("이름", "")`, `선택입력("이름", ["하나", "둘"], "하나")`로 입력값을 읽습니다.
+`"계산하기" 버튼을 누르면:` 뒤의 블록은 해당 버튼을 눌렀을 때 실행합니다.
+`버튼("이름")`도 같은 조건을 반환하며 `보여주기("이름", 값)`은 결과 카드를 만듭니다.
+버튼을 누를 때마다 현재 입력값으로 전체 프로그램을 다시 실행합니다. 일반 변수는 실행 사이에 유지되지 않습니다.
+이름은 중복할 수 없으며 한 실행당 최대 40개 화면 요소를 제공합니다.
+화면 함수는 데모 UI 실행 환경이 필요하며 Node CLI 단독 실행이나 React·Vue 컴포넌트 자동 생성 기능은 아닙니다.
 
-## 화면 함수와 버튼 블록
+## 실행·진단 범위
 
-UI 실행 환경에서는 `숫자입력("이름", 0)`, `글자입력("이름", "")`,
-`선택입력("이름", ["하나", "둘"], "하나")`로 현재 입력값을 읽습니다.
-`"계산하기" 버튼을 누르면:` 뒤의 들여쓴 블록은 해당 버튼을 눌렀을 때만 실행합니다.
-`보여주기("결과 이름", 값)`은 결과 카드를 생성합니다. `버튼("이름")`도 같은 조건을 반환합니다.
-버튼 실행은 현재 입력값을 사용한 전체 프로그램 재실행이며, 지속되는 변수나 DOM 이벤트 클로저가 아닙니다.
-화면 함수는 Node CLI 단독 실행에서 지원되지 않습니다.
+`ksc build`는 타입 검사 후 JS와 .d.ts를 생성합니다. `ksc run`은 신뢰하는 로컬 코드를 Node.js에서 실행합니다.
+`--typescript`는 중간 TypeScript 확인용 출력입니다. 별도의 소스 문법 모드가 아닙니다.
+웹 데모와 Vite 플러그인은 문법 변환·JS 구문 진단을 제공하며 전체 타입 검사는 하지 않습니다.
+문장 오류는 원본 행 번호를 표시합니다. TypeScript 타입 진단은 생성 코드 위치를 사용하며 원본 소스맵은 아직 제공하지 않습니다.
+임의의 한국어를 해석하는 AI 실행기·Python 호환 언어·전체 JavaScript/TypeScript 대체 언어가 아닙니다.

package/README.md

@@ -3,15 +3,14 @@
 [![CI on main](https://github.com/uiwwsw/hangulscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/uiwwsw/hangulscript/actions/workflows/ci.yml)
 [![MIT license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/uiwwsw/hangulscript/blob/main/LICENSE)
 
-**한글 문장으로 작성하고, JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어.**
+**한글 문장으로 작성하고, JavaScript와 타입 선언으로 배포하는 프로그래밍 언어.**
 
 Python의 들여쓰기와 익숙한 기본 함수, JavaScript의 표현식과 웹 생태계,
 TypeScript의 타입 검사를 결합합니다. 소스 확장자는 **`.hgs`**입니다.
 
-[온라인에서 실행하기](https://hangulscript.vercel.app/) · [문법 명세](LANGUAGE.md) · [릴리스](https://github.com/uiwwsw/hangulscript/releases) · [의견 보내기](https://github.com/uiwwsw/hangulscript/issues)
+[온라인에서 실행하기](https://hangulscript.vercel.app/) · [React·Vue 사용법](docs/frameworks.md) · [문법 명세](LANGUAGE.md) · [변경 내역](CHANGELOG.md) · [릴리스](https://github.com/uiwwsw/hangulscript/releases) · [의견 보내기](https://github.com/uiwwsw/hangulscript/issues)
 
-```ks
-문장으로 시작
+```text
 점수들은 [75, 92, 88]이다
 각 점수를 점수들에서:
     만약 점수 >= 80 이라면:
@@ -19,7 +18,7 @@ TypeScript의 타입 검사를 결합합니다. 소스 확장자는 **`.hgs`**
 출력("평균:", 평균(점수들))
 ```
 
-문장형은 실험판입니다. 정해진 한국어 문법을 파싱하며, 임의의 자연어를 추측해 실행하지 않습니다.
+정해진 한국어 문법을 파싱하며, 임의의 자연어를 추측해 실행하지 않습니다.
 Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습니다.
 
 ## 지금 만들 수 있는 것
@@ -34,13 +33,13 @@ Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습
 | [타입 있는 함수 모듈](examples/math-library.hgs) | 함수·타입 | JS + .d.ts 라이브러리 빌드 |
 
 데모에서 예제를 선택하고 입력값을 바꾼 다음 **실행하기**를 누르세요. 변환 결과는 기본적으로 JavaScript로 표시하며, 선택 메뉴에서 TypeScript와 비교할 수 있습니다. 실행 결과 패널은 데모를 스크롤하는 동안 화면 하단에 붙어 있습니다. CLI 빌드는 JavaScript와 `.d.ts`를 함께 생성합니다.
-입력값 변경은 예제 코드를 다시 생성하며, 코드를 직접 편집하면 입력란은 숨겨집니다.
-독립적인 웹 UI·데이터베이스·외부 API를 언어 자체에서 제공하는 단계는 아닙니다.
+화면 예제에서는 입력값을 바꾸고 도구 안의 버튼을 누르면 현재 값으로 프로그램을 다시 실행합니다.
+데모는 입력창·선택창·버튼·결과 카드를 제공합니다. 데이터베이스·외부 API는 제공하지 않습니다.
 생성한 JS를 기존 웹/Node 프로젝트에 연결해 화면과 서비스를 확장할 수 있습니다.
 
 ## 설치
 
-Node.js **20 이상**이 필요합니다. 아래의 JS + .d.ts 빌드와 `run` 명령은 **0.3.0부터** 제공합니다.
+Node.js **20.19 이상**이 필요합니다. 아래의 JS + .d.ts 빌드와 `run` 명령은 **0.3.0부터** 제공합니다.
 공개된 버전은 [npm](https://www.npmjs.com/package/@uiwwsw/hangulscript) 또는 `npm view @uiwwsw/hangulscript version`으로 확인하세요.
 
 ```bash
@@ -79,7 +78,7 @@ npx ksc --typescript examples/math-library.hgs --out-dir output
 ```
 
 **0.2에서 변경:** CLI의 기본 출력이 `.ts`에서 **`.js` + `.d.ts`**로 바뀝니다.
-기존 자동화가 `.ts`를 기대한다면 `--typescript`를 추가하세요.
+중간 TypeScript를 확인하려면 `--typescript`를 추가하세요. 소스는 문장형 하나만 지원합니다.
 `compileSource`·`compileString` API는 기존처럼 TypeScript 문자열을 반환합니다.
 
 `run`은 신뢰하는 코드를 로컬 Node.js에서 실행합니다. 온라인 데모와 달리 격리·2초 제한이 없습니다.
@@ -87,11 +86,10 @@ npx ksc --typescript examples/math-library.hgs --out-dir output
 
 ### 배포 산출물 사용
 
-```ks
-문장으로 시작
+```text
 더함(가: 숫자, 나: 숫자)를 정의한다:
     돌려주기 가 + 나
-내보내기 { 더함 }
+더함을 공개한다
 ```
 
 생성한 `.js`에는 실행 코드가, `.d.ts`에는 다음과 같은 타입 계약이 담깁니다.
@@ -114,8 +112,9 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 
 ## 문장형 문법
 
-```ks
-문장으로 시작
+문장형이 유일한 기본 문법입니다. 별도의 시작 문장 없이 첫 줄부터 작성합니다.
+
+```text
 이름은 "하늘"이다
 횟수는 3이다
 
@@ -136,16 +135,6 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 - 블록은 콜론 뒤에 공백으로 들여씁니다. 탭은 허용하지 않습니다.
 - 행 전체 주석은 `#`입니다. 표현식은 JS의 연산자·배열·객체를 사용합니다.
 
-기존 키워드형도 사용할 수 있습니다.
-
-```ks
-상수 이름 = "철수";
-함수 인사(사람: 문자열): 문자열 {
-  반환 "안녕, " + 사람;
-}
-콘솔.출력(인사(이름));
-```
-
 지원 범위와 제약은 [LANGUAGE.md](LANGUAGE.md)에 정리했습니다.
 
 ## 한글 기본 함수
@@ -189,17 +178,11 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 
 - **컴파일 전용 Worker:** TypeScript 파싱·변환·출력 정리를 UI 스레드 밖에서 실행.
 - **180ms 입력 지연과 결과 재사용:** 키를 누를 때마다 변환하지 않고, 같은 소스는 다시 컴파일하지 않음.
-- **키워드 첫 글자별 탐색:** 모든 문자에서 전체 키워드 목록을 순회하지 않음.
-- **불필요한 재처리 생략:** 기본 함수 코드를 다시 치환하지 않고, 클래스가 없으면 클래스 보정도 생략.
+- **단일 문장형 파서:** 모드 자동 감지·키워드 치환·클래스 사후 보정을 제거하고 문장 블록을 직접 생성.
 - **실행 출력 제한:** 부모 페이지에서도 최대 100행·행당 1,000자로 제한.
 - **범위 제한:** `범위`는 최대 100,000개 항목. 최솟값·최댓값은 인자 펼치기 없이 순회.
 
-2026-10-22 Node 24.18.0 환경에서 같은 1,000행 선언 코드를 측정했을 때,
-변환 중앙값은 변경 전 약 **4.45ms**, 변경 후 약 **0.65ms**였습니다.
-개선 후 20회 측정 p95는 약 **1.88ms**였고, 작은 코드의 타입 검사·JS/.d.ts 생성은 약 **168ms**였습니다.
-서로 다른 기기·입력·브라우저에서 같은 수치를 보장하는 벤치마크는 아닙니다.
-
-화면 JS는 약 **10.4KB**, 컴파일러 Worker는 약 **3.58MB**입니다(압축 전).
+성능은 `npm run benchmark`로 1,000행 문장형 선언의 변환 시간과 현재 번들 크기를 측정할 수 있습니다.
 Worker 분리는 UI의 파싱·실행 부담을 분리하지만 전체 다운로드를 제거하지 않습니다.
 첫 로딩은 네트워크와 기기에 따라 느릴 수 있습니다.
 
@@ -218,7 +201,7 @@ npm run benchmark
 ```js
 import { buildSource, lintSource } from '@uiwwsw/hangulscript';
 
-const source = '문장으로 시작\n출력(합계([1, 2, 3]))';
+const source = '출력(합계([1, 2, 3]))';
 const { javascript, declaration } = buildSource(source);
 const { hasErrors } = lintSource(source);
 ```
@@ -227,7 +210,7 @@ Node 파일 API 없이 변환만 필요하면:
 
 ```js
 import { compileSource } from '@uiwwsw/hangulscript/browser';
-const typescript = compileSource('문장으로 시작\n출력("안녕")');
+const typescript = compileSource('출력("안녕")');
 ```
 
 이 진입점도 TypeScript 스캐너를 포함합니다. 브라우저에서는 데모처럼 Worker에서 사용하세요.
@@ -246,16 +229,16 @@ npm pack --dry-run
 Vercel은 GitHub main과 연결되어 `site-dist/`를 배포합니다.
 `SITE_URL`에 HTTPS origin을 지정하면 canonical·Open Graph·robots·sitemap 주소를 바꿀 수 있습니다.
 
-향후에는 독립 AST·원본 `.hgs` 소스맵·LSP·모듈 그래프·Vite 연동 순으로 확장할 계획입니다.
+Vite 연동을 제공합니다. 독립 AST·원본 `.hgs` 소스맵·LSP·모듈 그래프는 향후 과제입니다.
 
 ## 라이선스
 
 [MIT](LICENSE)
 
-## 이름과 확장자 이전 (0.4)
+## 이름과 확장자
 
 제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
-기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
+0.6부터 소스 확장자는 `.hgs`만 지원하며 키워드형과 시작 표기를 제거했습니다. 기존 코드는 [문법 명세](LANGUAGE.md)의 문장형으로 옮겨야 합니다.
 이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.
 
 
@@ -264,7 +247,6 @@ Vercel은 GitHub main과 연결되어 `site-dist/`를 배포합니다.
 온라인 데모의 계산기·할인·통계·문자열 예제는 코드에 선언한 실제 화면을 제공합니다.
 
 ```text
-문장으로 시작
 가격은 숫자입력("상품 가격", 10000)이다
 할인율은 숫자입력("할인율", 20)이다
 
@@ -285,7 +267,11 @@ HTML·이벤트 핸들러 문자열을 삽입하지 않습니다.
 
 ## React·Vue에서 .hgs 가져오기
 
-Vite를 사용하는 React와 Vue는 별도 프레임워크 패키지 없이 같은 플러그인을 사용할 수 있습니다.
+**0.6.0 이상**의 공통 Vite 플러그인을 사용합니다. React/Vue의 화면과 상태 관리에 한글스크립트 계산·검증 함수를 연결할 수 있습니다.
+
+```bash
+npm install --save-dev @uiwwsw/hangulscript@^0.7.0
+```
 
 ```js
 // vite.config.js — React
@@ -296,21 +282,36 @@ import hangulscript from '@uiwwsw/hangulscript/vite';
 export default defineConfig({ plugins: [hangulscript(), react()] });
 ```
 
-Vue에서는 React 플러그인 대신 `@vitejs/plugin-vue`의 `vue()`를 넣습니다.
+Vue에서는 `@vitejs/plugin-vue`에서 `vue`를 가져와 `[hangulscript(), vue()]`로 설정합니다.
 
 ```text
-// src/discount.hgs
-export function 할인(가격: number, 비율: number) {
-    return 가격 * (1 - 비율 / 100);
-}
+결제금액(가격: number, 할인율: number)를 정의한다:
+    돌려주기 가격 - 반올림(가격 * 할인율 / 100)
+결제금액을 공개한다
 ```
 
 ```js
-// React 이벤트 핸들러와 Vue setup 등에서 동일하게 사용
-import { 할인 } from './discount.hgs';
-console.log(할인(10000, 20)); // 8000
+import { 결제금액 } from './discount.hgs';
+console.log(결제금액(10000, 20)); // 8000
 ```
 
-이 플러그인은 빌드 시 `.hgs`를 JavaScript 모듈로 변환합니다. React/Vue 컴포넌트는 각 프레임워크로 작성하고 한글스크립트 함수로 계산·검증 로직을 공유합니다.
-현재 플러그인은 타입 검사·선언 생성·소스맵을 제공하지 않습니다. 엄격한 타입 연동이 필요하면 `ksc build`로 만든 `.js`와 `.d.ts`를 가져오세요.
-데모의 UI 문장을 React/Vue 컴포넌트로 변환하는 기능은 포함하지 않습니다.
+완성된 **입력창 → 버튼 → 계산 결과** 예제와 React JSX·Vue SFC 전체 코드를 제공합니다.
+
+- [React·Vue 단계별 사용 안내](docs/frameworks.md): 설치·설정·한글 함수·컴포넌트 연결·TypeScript 사용법
+- [실행 가능한 React 예제](examples/react-vite): 해당 폴더에서 `npm ci` → `npm run dev`
+- [실행 가능한 Vue 예제](examples/vue-vite): 해당 폴더에서 `npm ci` → `npm run dev`
+- [온라인 연동 안내](https://hangulscript.vercel.app/#frameworks)
+
+예제는 Node.js `^20.19.0 || >=22.12.0`이 필요하며 Node.js 24에서 검증했습니다.
+**0.7.0부터** Vite 플러그인은 구문·타입 오류가 있으면 개발 서버와 빌드를 실패시키고 원본 `.hgs` 위치를 표시합니다. 선언 생성·디버깅 소스맵은 제공하지 않습니다. TypeScript 프로젝트는 `ksc build`로 생성한 `.js`와 `.d.ts`를 가져오는 방식이 적합합니다.
+데모의 UI 문장을 React/Vue 컴포넌트로 자동 변환하는 기능은 포함하지 않습니다.
+
+## VS Code 확장
+
+문법 강조·자동 들여쓰기·문서 포맷·Problems 오류 표시·타입 정보·정의 이동·스코프 자동 완성을 제공하는 확장을 같은 저장소의 [`extensions/vscode`](extensions/vscode)에서 개발합니다. [설치·저장 시 포맷·Marketplace 게시 안내](extensions/vscode/README.md)를 참고하세요. VSIX 패키지와 Marketplace 공개는 별도 단계입니다.
+
+## 공식 도구와 지원 범위
+
+Node에서 직접 실행하려면 `node --import @uiwwsw/hangulscript/register src/main.hgs`를 사용합니다. `ksc run`도 같은 로더를 사용하며 상대 경로 `.hgs` import를 처리합니다. `ksc build`는 진입 폴더 아래 HGS 모듈을 함께 빌드하고 import를 `.js`로 연결합니다.
+
+[환경별 지원 계약·타입 설정·호환성 정책](docs/support.md)을 확인하세요. 언어 패키지와 VS Code 확장은 같은 저장소에서 검증하며 별도 버전으로 배포합니다.

package/dist/checker.js

@@ -0,0 +1,80 @@
+import ts from 'typescript';
+import path from 'node:path';
+import { compileMappedSource } from './transformer.js';
+import { mapDiagnostic, syntaxDiagnostic } from './diagnostics.js';
+
+const libraryCache = new Map();
+export function analyzeSource(source, filePath = 'input.hgs', settings = {}) {
+  const configPath = ts.findConfigFile(path.dirname(path.resolve(filePath)), ts.sys.fileExists);
+  const configRead = configPath ? ts.readConfigFile(configPath, ts.sys.readFile) : undefined;
+  const converted = configRead?.config ? ts.parseJsonConfigFileContent(configRead.config, { ...ts.sys, readDirectory: () => [] }, path.dirname(configPath)) : { options: {}, errors: [] };
+  const options = {
+    strict: true, skipLibCheck: true, types: [],
+    ...converted.options, ...settings.compilerOptions,
+    target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler,
+    moduleDetection: ts.ModuleDetectionKind.Force, declaration: true, noEmitOnError: true,
+    noEmit: false, emitDeclarationOnly: false, outDir: undefined, outFile: undefined, rootDir: undefined, incremental: false, composite: false, sourceMap: false, declarationMap: false, inlineSourceMap: false
+  };
+  const originals = new Map([...settings.files ?? []].map(([name, text]) => [path.resolve(name), text]));
+  const root = path.resolve(filePath);
+  originals.set(root, source);
+  const virtual = name => name + '.ts';
+  const documents = new Map();
+  const syntaxErrors = [];
+  const base = ts.createCompilerHost(options, true);
+  const libDirectory = settings.libDirectory ?? path.dirname(ts.getDefaultLibFilePath(options));
+  function document(name) {
+    if (documents.has(virtual(name))) return documents.get(virtual(name));
+    const text = originals.get(name) ?? ts.sys.readFile(name);
+    if (text === undefined) return null;
+    let mapped;
+    try { mapped = compileMappedSource(text); }
+    catch (error) { syntaxErrors.push(syntaxDiagnostic(error, text, name)); mapped = { code: 'export {};', lineMap: [1] }; }
+    const result = { ...mapped, source: text, filePath: name };
+    documents.set(virtual(name), result);
+    return result;
+  }
+  const isVirtual = name => name.endsWith('.hgs.ts') || originals.has(name.slice(0, -3));
+  const host = {
+    ...base,
+    getCurrentDirectory: () => configPath ? path.dirname(configPath) : path.dirname(root),
+    getDefaultLibFileName: () => path.join(libDirectory, ts.getDefaultLibFileName(options)),
+    getDefaultLibLocation: () => libDirectory,
+    fileExists(name) { return isVirtual(name) ? originals.has(name.slice(0, -3)) || ts.sys.fileExists(name.slice(0, -3)) : base.fileExists(name); },
+    readFile(name) { return isVirtual(name) ? document(name.slice(0, -3))?.code : base.readFile(name); },
+    getSourceFile(name, languageVersion) {
+      const text = isVirtual(name) ? document(name.slice(0, -3))?.code : base.readFile(name);
+      if (text === undefined) return undefined;
+      if (name.startsWith(libDirectory) && name.endsWith('.d.ts')) {
+        const cached = libraryCache.get(name);
+        if (cached?.text === text) return cached;
+        const file = ts.createSourceFile(name, text, languageVersion, true); libraryCache.set(name, file); return file;
+      }
+      return ts.createSourceFile(name, text, languageVersion, true);
+    },
+    resolveModuleNames(names, containingFile) {
+      return names.map(name => {
+        if (name.endsWith('.hgs') && name.startsWith('.')) {
+          const original = path.resolve(path.dirname(containingFile), name);
+          if (originals.has(original) || ts.sys.fileExists(original)) return { resolvedFileName: virtual(original), extension: ts.Extension.Ts };
+        }
+        return ts.resolveModuleName(name, containingFile, options, host).resolvedModule;
+      });
+    }
+  };
+  const roots = settings.allFiles ? [...originals.keys()] : [root];
+  const program = ts.createProgram(roots.map(virtual), options, host);
+  const nativeDiagnostics = ts.getPreEmitDiagnostics(program).filter(d => {
+    if (![6133, 6196].includes(d.code) || !d.file || d.start === undefined) return true;
+    const doc = documents.get(d.file.fileName);
+    return !doc || Boolean(doc.lineMap[d.file.getLineAndCharacterOfPosition(d.start).line]);
+  });
+  const configErrors = [...converted.errors.filter(d => d.code !== 18003), ...(configRead?.error ? [configRead.error] : [])].map(d => ({ ...mapDiagnostic(d, documents), filePath: configPath ?? root }));
+  const diagnostics = [...configErrors, ...syntaxErrors, ...nativeDiagnostics.map(d => mapDiagnostic(d, documents))];
+  return { program, documents, diagnostics, nativeDiagnostics, virtualRoot: virtual(root), compiled: documents.get(virtual(root))?.code ?? '', hasErrors: diagnostics.some(d => d.severity === 'error') };
+}
+
+export function checkSource(source, filePath = 'input.hgs', settings = {}) {
+  const { diagnostics, hasErrors } = analyzeSource(source, filePath, settings);
+  return { diagnostics, hasErrors };
+}

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { compileFileToDefaultDestination, compileFile, lintFile, buildFile, buildSource } from './index.js';
-import { readFile } from 'node:fs/promises';
+import { compileFileToDefaultDestination, compileFile, lintFile, buildFile } from './index.js';
+import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 
@@ -12,10 +12,10 @@ function usage() {
 옵션:
   -o, --out-dir <경로>   출력 디렉터리 (기본: 입력 파일 옆)
   --check                타입 검사만 실행
-  --typescript           기존 .ts 출력 모드
+  --typescript           변환된 TypeScript 확인용 출력
   -h, --help             도움말
 
-문장형은 실험판입니다. run은 신뢰하는 로컬 코드만 실행하세요.`);
+run은 신뢰하는 로컬 코드만 실행하세요.`);
 }
 
 async function main() {
@@ -34,7 +34,7 @@ async function main() {
     } else if (arg === '--check') check = true;
     else if (arg === '--typescript') typescript = true;
     else if (arg.startsWith('-')) throw new Error(`알 수 없는 옵션: ${arg}`);
-    else if (!(/\.(?:hgs|ks)$/.test(arg))) throw new Error('입력 파일은 .hgs 확장자여야 합니다.');
+    else if (!(/\.hgs$/.test(arg))) throw new Error('입력 파일은 .hgs 확장자여야 합니다.');
     else inputs.push(arg);
   }
   if (!inputs.length) throw new Error('입력 .hgs 파일을 지정하세요.');
@@ -42,13 +42,9 @@ async function main() {
   if (mode === 'run') {
     if (inputs.length !== 1 || outDir || typescript || check) throw new Error('run에는 .hgs 파일 하나와 -- 뒤의 실행 인자만 지정하세요.');
     const input = path.resolve(inputs[0]);
-    const { javascript } = buildSource(await readFile(input, 'utf8'), input);
-    const child = spawn(process.execPath, ['--input-type=module', '-', ...programArgs], {
-      cwd: path.dirname(input), stdio: ['pipe', 'inherit', 'inherit']
+    const child = spawn(process.execPath, ['--import', fileURLToPath(new URL('./register.js', import.meta.url)), input, ...programArgs], {
+      cwd: path.dirname(input), stdio: 'inherit'
     });
-    // Preserve imports relative to the source directory. Runtime needs Node.js 20+.
-    child.stdin.on('error', () => {});
-    child.stdin.end(javascript);
     const exitCode = await new Promise((resolve, reject) => {
       child.once('error', reject);
       child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));