@uiwwsw/hangulscript 0.0.0-stage → 0.4.0

package/LANGUAGE.md

@@ -0,0 +1,97 @@
+# 문장형 HangulScript v0.1 (실험판)
+
+`.hgs`를 TypeScript로 변환한다. Python의 들여쓰기·단순한 함수·기본 함수를
+받아들이고, JS의 배열·객체·표현식과 TypeScript 타입을 활용한다.
+Python 소스 호환 언어나 임의의 한국어를 해석하는 AI 실행기가 아니다.
+
+## 문법
+
+파일 첫 줄 `문장으로 시작`으로 문장형을 명시하는 것을 권장한다.
+변수 선언·각 반복·함수 정의 문장으로도 자동 감지한다.
+기존 `.hgs` 키워드형은 계속 지원한다. 같은 파일 안에서는 하나의 방식을 사용한다.
+공백 들여쓰기 폭은 자유지만 같은 블록은 동일해야 하고 탭은 허용하지 않는다.
+`#`는 행 전체 주석이다. 문장 끝 주석은 현재 지원하지 않는다.
+
+```ks
+문장으로 시작
+이름은 "하늘"이다
+횟수는 3이다
+
+인사(누구)를 정의한다:
+    돌려주기 "안녕, " + 누구
+
+각 순서를 범위(횟수)에서:
+    만약 순서 == 0 이라면:
+        출력("처음")
+    아니고 순서 == 1 이라면:
+        출력("다음")
+    아니면:
+        출력(인사(이름))
+
+동안 횟수 > 0:
+    횟수 = 횟수 - 1
+    만약 횟수 == 1 이라면:
+        멈추기
+```
+
+- 선언: `이름은 값이다` / `이름는 값이다`. 은·는은 문법적으로 둘 다 허용한다.
+  `let`으로 변환하며 재대입은 `이름 = 값`이다. 같은 범위에서 재선언할 수 없다. 빈 목록은 동적 목록 `any[]`로 생성한다.
+- 함수: `이름(인자)를 정의한다:`. 타입 없는 인자는 `any`로 변환한다.
+  `이름(인자: 문자열)를 정의한다:`처럼 타입을 명시할 수 있다.
+- 반환: `돌려주기 값`; 값 없이도 가능하다.
+- 조건: `만약 식 이라면:` / `아니고 식 이라면:` / `아니면:`.
+- 반복: `각 항목을 목록에서:`; 조사 을·를 모두 허용한다.
+- 조건 반복: `동안 식:`; `멈추기`, `계속하기`를 제공한다.
+- 식: JS의 연산자, 배열, 객체를 사용한다. 참·거짓·비어있음은 기존 변환을 따른다.
+  Python의 `and`, `or`, `in`, 리스트 컴프리헨션, 음수 인덱스는 제공하지 않는다.
+
+## 기본 함수
+
+| 함수 | 의미 |
+| --- | --- |
+| `출력(...값)` | 콘솔 출력 |
+| `길이(문자열 또는 목록)` | UTF-16 코드 단위 또는 항목 수 |
+| `합계(숫자목록)` | 합산 |
+| `정렬(숫자목록)` | 원본을 바꾸지 않고 오름차순 정렬 |
+| `범위(끝)` / `범위(시작, 끝, 간격)` | 끝 제외, 음수 간격 지원, 최대 10만 항목 |
+| `추가(목록, 값)` | 원본 목록에 추가 |
+| `포함(목록, 값)` | 포함 여부 |
+| `나누기(문자열, 구분자)` | 문자열 분리 |
+| `잇기(목록, 구분자)` | 기본 구분자 빈 문자열로 연결 |
+
+위 이름은 문장형 파일에 생성하는 기본 함수이므로 사용자 함수·변수 이름으로 쓰지 않는다.
+생성한 TypeScript에는 기본 함수의 구현이 포함된다. 독립 모듈로 사용하려면
+TypeScript 프로젝트의 moduleDetection 설정 또는 export로 모듈 범위를 지정한다.
+
+## 다음 개선 우선순위
+
+1. **독립 토큰화와 AST**: 현재 행 기반 문장 파서·키워드 치환기를 통합한다.
+   정규식 리터럴, 여러 줄 식, 복잡한 클래스/제네릭 문법은 완전 지원 범위가 아니다.
+2. **원본 위치 진단과 소스맵**: 들여쓰기 오류는 .hgs 행 번호를 표시하지만
+   TypeScript 타입 진단은 현재 확장된 생성 코드 위치를 사용한다.
+3. **표준 라이브러리 계약**: 문자열/목록/사전/날짜를 같은 함수 체계로 확장하고
+   Unicode 문자 수·동등성·정렬·오류 모델을 명시한다.
+4. **VS Code/LSP**: 강조, 자동 완성, 한글 오류 설명, 포맷터를 추가한다.
+5. **웹 프로젝트 통합**: Vite 플러그인과 .hgs 모듈 그래프를 구현한다.
+   현재 CLI는 파일 단위 변환이며 .hgs import 경로를 재작성하지 않는다.
+
+문장형은 실험판이다. 웹 데모는 문법 변환·JS 구문 진단만 하며 전체 타입 검사는 하지 않는다.
+DOM과 네트워크가 필요한 결과물은 신뢰하는 로컬 프로젝트에서 생성 TS를 통합해 만든다.
+
+## 0.3 실행·출력과 추가 함수
+
+CLI의 기본 빌드는 `.js` + `.d.ts`이며 `--typescript`로 기존 TS 출력을 선택한다.
+`ksc run 파일.hgs`는 생성 파일 없이 타입 검사 후 Node.js에서 실행한다.
+JS 출력은 ESM이며, 프로젝트는 `type: module` 또는 ESM 번들러를 사용한다.
+공개 함수에 `내보내기 { 함수이름 }`을 쓰면 해당 타입을 .d.ts로 배포할 수 있다.
+
+추가 기본 함수: `숫자로(값)`, `다듬기(문자열)`, `반올림(값, 자리=0)`,
+`평균(목록)`, `최솟값(목록)`, `최댓값(목록)`.
+평균/최솟값/최댓값의 빈 목록과 숫자로의 빈 문자열·비유한 숫자는 오류다.
+반올림은 JS Math.round 규칙이며 십진 임의 정밀도나 Python round와 같은 규칙을 보장하지 않는다.
+
+## 이름과 확장자 이전 (0.4)
+
+제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
+기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
+이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 uiwwsw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# 한글스크립트 · HangulScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**한글 문장으로 작성하고, JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어.**
+
+Python의 들여쓰기와 익숙한 기본 함수, JavaScript의 표현식과 웹 생태계,
+TypeScript의 타입 검사를 결합합니다. 소스 확장자는 **`.hgs`**입니다.
+
+[온라인에서 실행하기](https://hangulscript.vercel.app/) · [문법 명세](LANGUAGE.md) · [릴리스](https://github.com/uiwwsw/hangulscript/releases) · [의견 보내기](https://github.com/uiwwsw/hangulscript/issues)
+
+```ks
+문장으로 시작
+점수들은 [75, 92, 88]이다
+각 점수를 점수들에서:
+    만약 점수 >= 80 이라면:
+        출력(점수)
+출력("평균:", 평균(점수들))
+```
+
+문장형은 실험판입니다. 정해진 한국어 문법을 파싱하며, 임의의 자연어를 추측해 실행하지 않습니다.
+Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습니다.
+
+## 지금 만들 수 있는 것
+
+| 예제 | 바꿀 수 있는 값 | 사용하는 기능 |
+| --- | --- | --- |
+| [사칙연산 계산기](examples/calculator.hgs) | 두 숫자·연산 | 함수·조건·0 나눗셈 처리 |
+| [할인 계산기](examples/discount.hgs) | 가격·할인율 | 범위 검사·반올림 |
+| [숫자 통계](examples/statistics.hgs) | 쉼표로 구분한 숫자 | 합계·평균·최솟값·최댓값 |
+| [문자열 정리기](examples/text.hgs) | 단어 목록 | 공백 정리·중복 제거·연결 |
+| [성적 분석기](examples/scores.hgs) | 점수 목록 | 반복·필터링·정렬 |
+| [타입 있는 함수 모듈](examples/math-library.hgs) | 함수·타입 | JS + .d.ts 라이브러리 빌드 |
+
+데모에서 예제를 선택하고 입력값을 바꾼 다음 **실행하기**를 누르세요.
+입력값 변경은 예제 코드를 다시 생성하며, 코드를 직접 편집하면 입력란은 숨겨집니다.
+독립적인 웹 UI·데이터베이스·외부 API를 언어 자체에서 제공하는 단계는 아닙니다.
+생성한 JS를 기존 웹/Node 프로젝트에 연결해 화면과 서비스를 확장할 수 있습니다.
+
+## 설치
+
+Node.js **20 이상**이 필요합니다. 아래의 JS + .d.ts 빌드와 `run` 명령은 **0.3.0부터** 제공합니다.
+공개된 버전은 [npm](https://www.npmjs.com/package/@uiwwsw/hangulscript) 또는 `npm view @uiwwsw/hangulscript version`으로 확인하세요.
+
+```bash
+npm install --save-dev @uiwwsw/hangulscript
+```
+
+소스에서 최신 버전을 사용하려면:
+
+```bash
+git clone https://github.com/uiwwsw/hangulscript.git
+cd hangulscript
+npm ci
+npm run build
+node dist/cli.js run examples/calculator.hgs
+```
+
+## 직접 실행과 빌드
+
+```bash
+# .hgs를 바로 실행: 중간 파일을 만들지 않음
+npx ksc run examples/calculator.hgs
+
+# 기본 출력은 .js + .d.ts
+npx ksc build examples/math-library.hgs --out-dir output
+# output/math-library.js
+# output/math-library.d.ts
+
+# build 생략 가능
+npx ksc examples/math-library.hgs --out-dir output
+
+# 타입 검사만 수행
+npx ksc --check examples/math-library.hgs
+
+# 기존 .ts 출력이 필요할 때
+npx ksc --typescript examples/math-library.hgs --out-dir output
+```
+
+**0.2에서 변경:** CLI의 기본 출력이 `.ts`에서 **`.js` + `.d.ts`**로 바뀝니다.
+기존 자동화가 `.ts`를 기대한다면 `--typescript`를 추가하세요.
+`compileSource`·`compileString` API는 기존처럼 TypeScript 문자열을 반환합니다.
+
+`run`은 신뢰하는 코드를 로컬 Node.js에서 실행합니다. 온라인 데모와 달리 격리·2초 제한이 없습니다.
+프로그램 인자는 `ksc run 파일.hgs -- 인자1 인자2`처럼 전달합니다.
+
+### 배포 산출물 사용
+
+```ks
+문장으로 시작
+더함(가: 숫자, 나: 숫자)를 정의한다:
+    돌려주기 가 + 나
+내보내기 { 더함 }
+```
+
+생성한 `.js`에는 실행 코드가, `.d.ts`에는 다음과 같은 타입 계약이 담깁니다.
+
+```ts
+declare function 더함(가: number, 나: number): number;
+export { 더함 };
+```
+
+```js
+import { 더함 } from './output/math-library.js';
+console.log(더함(2, 3)); // 5
+```
+
+출력은 **ES Modules**입니다. Node 프로젝트에는 `package.json`의 `"type": "module"`을 설정하거나
+ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포하면 TypeScript 사용자가 타입을 읽을 수 있습니다.
+`.d.ts`는 실행 파일이 아닙니다. 함수 인자 타입을 생략하면 `any`가 되므로
+공개 라이브러리 함수에는 타입을 명시하는 편이 좋습니다.
+여러 `.hgs` 파일의 import 경로를 자동으로 묶거나 재작성하지는 않습니다.
+
+## 문장형 문법
+
+```ks
+문장으로 시작
+이름은 "하늘"이다
+횟수는 3이다
+
+인사(누구: 문자열)를 정의한다:
+    돌려주기 "안녕, " + 누구
+
+각 순서를 범위(횟수)에서:
+    만약 순서 == 0 이라면:
+        출력("첫 인사")
+    아니면:
+        출력(인사(이름))
+```
+
+- 선언: `이름은 값이다` 또는 `이름는 값이다`. 재대입은 `이름 = 값`.
+- 함수: `인사(누구)를 정의한다:`와 `돌려주기 값`.
+- 조건: `만약 식 이라면:` → `아니고 식 이라면:` → `아니면:`.
+- 반복: `각 항목을 목록에서:`와 `동안 식:`. `멈추기`, `계속하기` 지원.
+- 블록은 콜론 뒤에 공백으로 들여씁니다. 탭은 허용하지 않습니다.
+- 행 전체 주석은 `#`입니다. 표현식은 JS의 연산자·배열·객체를 사용합니다.
+
+기존 키워드형도 사용할 수 있습니다.
+
+```ks
+상수 이름 = "철수";
+함수 인사(사람: 문자열): 문자열 {
+  반환 "안녕, " + 사람;
+}
+콘솔.출력(인사(이름));
+```
+
+지원 범위와 제약은 [LANGUAGE.md](LANGUAGE.md)에 정리했습니다.
+
+## 한글 기본 함수
+
+문장형 파일에는 다음 함수가 제공됩니다.
+
+| 함수 | 예시 / 의미 |
+| --- | --- |
+| `출력` | `출력("합계:", 30)` |
+| `길이` | 문자열의 UTF-16 코드 단위 수 또는 목록 항목 수 |
+| `추가` | `추가(목록, 값)` — 원본 목록 변경 |
+| `포함` | `포함(목록, 값)` — 포함 여부 |
+| `나누기` | `나누기("가,나", ",")` |
+| `잇기` | `잇기(["가", "나"], " · ")` |
+| `다듬기` | 문자열 양 끝 공백 제거 |
+| `숫자로` | 유한한 숫자로 변환, 빈 문자열·잘못된 값은 오류 |
+| `합계` | 숫자 목록 합산 |
+| `평균` | 숫자 목록 평균, 빈 목록은 오류 |
+| `최솟값` / `최댓값` | 목록을 순회해 계산, 빈 목록은 오류 |
+| `반올림` | `반올림(12.345, 2)` — 자리 -10~10 |
+| `정렬` | 숫자 목록을 복사해 오름차순 정렬 |
+| `범위` | `범위(5)`, `범위(1, 5)`, `범위(5, 0, -1)` — 끝 제외 |
+
+계산은 JS의 부동소수점 규칙을 따릅니다. 예를 들어 `0.1 + 0.2`의 정밀도는
+이 언어에서도 달라지지 않습니다. 금액은 원·센트 같은 정수 단위로 다루세요.
+`반올림`은 JS `Math.round` 규칙이며 임의 정밀도 십진 연산이 아닙니다.
+
+## 공유
+
+1. 데모에서 예제를 수정하고 실행 결과를 확인합니다.
+2. **공유 링크 복사**로 코드를 담은 URL을 전달합니다.
+3. 받는 사람은 코드를 읽고 직접 실행합니다. 링크를 열기만 해서는 실행되지 않습니다.
+4. **.hgs 저장**으로 소스를 내려받아 CLI에서 실행하거나 JS + .d.ts로 배포합니다.
+
+코드는 URL의 `#code=` 조각에 담깁니다. 서버 저장소·공개 코드 목록 기능은 없습니다.
+링크를 가진 사람이 코드를 읽을 수 있으므로 비밀번호·토큰·개인정보는 넣지 마세요.
+
+## 성능과 실행 제한
+
+0.3에서 다음 개선을 적용했습니다.
+
+- **컴파일 전용 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**입니다(압축 전).
+Worker 분리는 UI의 파싱·실행 부담을 분리하지만 전체 다운로드를 제거하지 않습니다.
+첫 로딩은 네트워크와 기기에 따라 느릴 수 있습니다.
+
+```bash
+npm run build:site
+npm run benchmark
+```
+
+온라인 실행은 별도 origin의 sandbox iframe과 Worker에서 최대 2초 동안 수행합니다.
+네트워크·DOM·외부 모듈은 제공하지 않으며 입력은 30,000자로 제한합니다.
+이는 완전한 메모리 할당 제한이 아닙니다. 매우 큰 배열 등은 Worker에서도 메모리를 많이 사용할 수 있습니다.
+대용량 작업·프로덕션 서버용 성능을 검증한 단계는 아닙니다.
+
+## 프로그래밍 API
+
+```js
+import { buildSource, lintSource } from '@uiwwsw/hangulscript';
+
+const source = '문장으로 시작\n출력(합계([1, 2, 3]))';
+const { javascript, declaration } = buildSource(source);
+const { hasErrors } = lintSource(source);
+```
+
+Node 파일 API 없이 변환만 필요하면:
+
+```js
+import { compileSource } from '@uiwwsw/hangulscript/browser';
+const typescript = compileSource('문장으로 시작\n출력("안녕")');
+```
+
+이 진입점도 TypeScript 스캐너를 포함합니다. 브라우저에서는 데모처럼 Worker에서 사용하세요.
+루트와 브라우저 진입점 모두 패키지의 `.d.ts`를 제공합니다.
+
+## 개발·배포
+
+```bash
+npm ci
+npm test
+npm run build
+npm run build:site
+npm pack --dry-run
+```
+
+Vercel은 GitHub main과 연결되어 `site-dist/`를 배포합니다.
+`SITE_URL`에 HTTPS origin을 지정하면 canonical·Open Graph·robots·sitemap 주소를 바꿀 수 있습니다.
+
+향후에는 독립 AST·원본 `.hgs` 소스맵·LSP·모듈 그래프·Vite 연동 순으로 확장할 계획입니다.
+
+## 라이선스
+
+[MIT](LICENSE)
+
+## 이름과 확장자 이전 (0.4)
+
+제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
+기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
+이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { compileFileToDefaultDestination, compileFile, lintFile, buildFile, buildSource } from './index.js';
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+function usage() {
+  console.log(`사용법:
+  ksc [build] [옵션] <파일.hgs ...>  JavaScript와 .d.ts 생성
+  ksc run <파일.hgs> [-- 인자 ...]   파일 없이 Node.js로 직접 실행
+
+옵션:
+  -o, --out-dir <경로>   출력 디렉터리 (기본: 입력 파일 옆)
+  --check                타입 검사만 실행
+  --typescript           기존 .ts 출력 모드
+  -h, --help             도움말
+
+문장형은 실험판입니다. run은 신뢰하는 로컬 코드만 실행하세요.`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (!args.length) { usage(); process.exitCode = 1; return; }
+  if (args.includes('--help') || args.includes('-h')) { usage(); return; }
+  const mode = ['run', 'build'].includes(args[0]) ? args.shift() : 'build';
+  let outDir, check = false, typescript = false;
+  const inputs = [], programArgs = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--' && mode === 'run') { programArgs.push(...args.slice(index + 1)); break; }
+    if (arg === '--out-dir' || arg === '-o') {
+      outDir = args[++index];
+      if (!outDir || outDir.startsWith('-')) throw new Error('--out-dir에는 경로가 필요합니다.');
+    } 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 inputs.push(arg);
+  }
+  if (!inputs.length) throw new Error('입력 .hgs 파일을 지정하세요.');
+  if (check && (outDir || typescript)) throw new Error('--check는 출력 옵션과 함께 사용할 수 없습니다.');
+  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']
+    });
+    // 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)));
+    });
+    process.exitCode = exitCode;
+    return;
+  }
+  const destinations = new Set();
+  for (const input of inputs) {
+    const destination = path.resolve(outDir ?? path.dirname(input), path.parse(input).name);
+    if (destinations.has(destination)) throw new Error('출력 파일 이름이 겹칩니다. 파일별로 다른 출력 디렉터리를 사용하세요.');
+    destinations.add(destination);
+  }
+  for (const input of inputs) {
+    if (check) {
+      const result = await lintFile(input);
+      if (result.hasErrors) throw new Error(result.formattedDiagnostics);
+      console.log(`✅ ${input} 문제 없음`);
+    } else if (typescript) {
+      const output = outDir ? path.join(outDir, path.parse(input).name + '.ts') : null;
+      const written = output ? (await compileFile(input, output), output) : await compileFileToDefaultDestination(input);
+      console.log(`✅ ${written} 생성됨`);
+    } else {
+      const result = await buildFile(input, outDir);
+      console.log(`✅ ${result.javascriptPath}\n✅ ${result.declarationPath}`);
+    }
+  }
+}
+main().catch(error => { console.error(`오류: ${error.message}`); process.exitCode = 1; });

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type * as ts from 'typescript';
+export { compileSource } from './transformer.js';
+export function compileString(source: string): string;
+export function compileFile(inputPath: string, outputPath: string): Promise<string>;
+export function compileFileToDefaultDestination(inputPath: string): Promise<string>;
+export interface LintResult {
+  diagnostics: readonly ts.Diagnostic[];
+  formattedDiagnostics: string;
+  hasErrors: boolean;
+}
+export function lintSource(source: string, filePath?: string, compilerOptions?: ts.CompilerOptions): LintResult;
+export function lintFile(inputPath: string, compilerOptions?: ts.CompilerOptions): Promise<LintResult>;
+export interface BuildResult { javascript: string; declaration: string; }
+export function buildSource(source: string, filePath?: string): BuildResult;
+export function buildFile(inputPath: string, outputDirectory?: string): Promise<BuildResult & { javascriptPath: string; declarationPath: string }>;

package/dist/index.js

@@ -0,0 +1,181 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { compileSource } from './transformer.js';
+
+const require = createRequire(import.meta.url);
+let tsModuleCache;
+let defaultCompilerOptions;
+
+function loadTypeScriptModule() {
+  if (tsModuleCache) {
+    return tsModuleCache;
+  }
+  let typescript;
+  try {
+    typescript = require('typescript');
+  } catch (initialError) {
+    const globalCandidate = path.join(process.execPath, '..', '..', 'lib', 'node_modules', 'typescript');
+    try {
+      typescript = require(globalCandidate);
+    } catch (fallbackError) {
+      throw new Error('TypeScript 모듈을 불러올 수 없습니다. Bun 또는 Node 환경에서 TypeScript를 설치해주세요.');
+    }
+  }
+  tsModuleCache = typescript.default ?? typescript;
+  return tsModuleCache;
+}
+
+function getDefaultCompilerOptions(ts) {
+  if (!defaultCompilerOptions) {
+    defaultCompilerOptions = {
+      allowNonTsExtensions: true,
+      noEmit: true,
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2020,
+      strict: true,
+      esModuleInterop: true
+    };
+  }
+  return defaultCompilerOptions;
+}
+
+function createLintHost(ts, compilerOptions, filePath, sourceText) {
+  const resolvedFilePath = path.resolve(filePath);
+  const baseHost = ts.createCompilerHost(compilerOptions, true);
+  const sourceFile = ts.createSourceFile(
+    resolvedFilePath,
+    sourceText,
+    compilerOptions.target ?? ts.ScriptTarget.ES2020,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  const getSourceFile = baseHost.getSourceFile.bind(baseHost);
+  const fileExists = baseHost.fileExists.bind(baseHost);
+  const readFile = baseHost.readFile.bind(baseHost);
+
+  baseHost.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+    if (path.resolve(fileName) === resolvedFilePath) {
+      return shouldCreateNewSourceFile ? ts.createSourceFile(
+        resolvedFilePath,
+        sourceText,
+        languageVersion,
+        true,
+        ts.ScriptKind.TS
+      ) : sourceFile;
+    }
+    return getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+  };
+
+  baseHost.fileExists = (fileName) => {
+    if (path.resolve(fileName) === resolvedFilePath) {
+      return true;
+    }
+    return fileExists(fileName);
+  };
+
+  baseHost.readFile = (fileName) => {
+    if (path.resolve(fileName) === resolvedFilePath) {
+      return sourceText;
+    }
+    return readFile(fileName);
+  };
+
+  return baseHost;
+}
+
+function formatDiagnostics(ts, diagnostics) {
+  if (diagnostics.length === 0) {
+    return '';
+  }
+  const formatHost = {
+    getCanonicalFileName: (fileName) => fileName,
+    getCurrentDirectory: () => process.cwd(),
+    getNewLine: () => '\n'
+  };
+  return ts.formatDiagnosticsWithColorAndContext(diagnostics, formatHost);
+}
+
+export function compileString(source) {
+  return compileSource(source);
+}
+
+export async function compileFile(inputPath, outputPath) {
+  const source = await readFile(inputPath, 'utf8');
+  const compiled = compileSource(source);
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, compiled, 'utf8');
+  return compiled;
+}
+
+export async function compileFileToDefaultDestination(inputPath) {
+  const parsed = path.parse(inputPath);
+  const outputPath = path.join(parsed.dir, `${parsed.name}.ts`);
+  await compileFile(inputPath, outputPath);
+  return outputPath;
+}
+
+export function lintSource(source, filePath = 'input.hgs', compilerOptions) {
+  const ts = loadTypeScriptModule();
+  const options = compilerOptions ?? getDefaultCompilerOptions(ts);
+  const compiled = compileSource(source);
+  const host = createLintHost(ts, options, filePath, compiled);
+  const program = ts.createProgram([path.resolve(filePath)], options, host);
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  return {
+    diagnostics,
+    formattedDiagnostics: formatDiagnostics(ts, diagnostics),
+    hasErrors: diagnostics.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
+  };
+}
+
+export async function lintFile(inputPath, compilerOptions) {
+  const source = await readFile(inputPath, 'utf8');
+  return lintSource(source, inputPath, compilerOptions);
+}
+
+export { compileSource };
+
+/** Compile through TypeScript once, emitting executable JS and declarations in memory. */
+export function buildSource(source, filePath = 'input.hgs') {
+  const ts = loadTypeScriptModule();
+  const virtualPath = path.resolve(filePath).replace(/\.(?:hgs|ks)$/i, '') + '.ts';
+  const compiled = compileSource(source);
+  const options = {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    declaration: true,
+    noEmitOnError: true,
+    skipLibCheck: true
+  };
+  const host = createLintHost(ts, options, virtualPath, compiled);
+  const files = new Map();
+  host.writeFile = (name, content) => files.set(name, content);
+  const program = ts.createProgram([virtualPath], options, host);
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  if (diagnostics.some(d => d.category === ts.DiagnosticCategory.Error)) {
+    throw new Error(formatDiagnostics(ts, diagnostics));
+  }
+  const emitted = program.emit();
+  if (emitted.emitSkipped) throw new Error(formatDiagnostics(ts, emitted.diagnostics) || '빌드에 실패했습니다.');
+  return {
+    javascript: files.get(virtualPath.replace(/\.ts$/, '.js')) ?? '',
+    declaration: files.get(virtualPath.replace(/\.ts$/, '.d.ts')) ?? ''
+  };
+}
+
+export async function buildFile(inputPath, outputDirectory = path.dirname(inputPath)) {
+  const source = await readFile(inputPath, 'utf8');
+  const result = buildSource(source, inputPath);
+  const base = path.parse(inputPath).name;
+  await mkdir(outputDirectory, { recursive: true });
+  const javascriptPath = path.join(outputDirectory, base + '.js');
+  const declarationPath = path.join(outputDirectory, base + '.d.ts');
+  await writeFile(javascriptPath, result.javascript, 'utf8');
+  await writeFile(declarationPath, result.declaration, 'utf8');
+  return { ...result, javascriptPath, declarationPath };
+}

package/dist/sentences.js

@@ -0,0 +1,99 @@
+// 문장형 v0.1: deterministic indentation grammar, not natural-language inference.
+export function isSentenceSource(source) {
+  return source.split(/\r?\n/).some(line => /^\s*(?:문장으로 시작\s*$|[\p{L}_$][\p{L}\p{N}_$]*(?:은|는)\s+.+이다\s*$|각 .+에서:\s*$|[\p{L}_$][\p{L}\p{N}_$]*\(.*\)를 정의한다:\s*$)/u.test(line));
+}
+
+export const sentenceRuntime = `
+function 출력(...값: unknown[]): void { console.log(...값); }
+function 길이(값: string | readonly unknown[]): number { return 값.length; }
+function 추가<T>(목록: T[], 값: T): void { 목록.push(값); }
+function 포함<T>(목록: readonly T[], 값: T): boolean { return 목록.includes(값); }
+function 나누기(글: string, 구분: string): string[] { return 글.split(구분); }
+function 잇기(목록: readonly unknown[], 구분 = ""): string { return 목록.join(구분); }
+function 합계(값: readonly number[]): number { return 값.reduce((합, 항목) => 합 + 항목, 0); }
+function 숫자로(값: string | number): number {
+  if (typeof 값 === "string" && 값.trim() === "") throw new Error("빈 문자열은 숫자로 바꿀 수 없습니다.");
+  const 결과 = Number(값);
+  if (!Number.isFinite(결과)) throw new Error("유한한 숫자를 입력하세요.");
+  return 결과;
+}
+function 다듬기(글: string): string { return 글.trim(); }
+function 반올림(값: number, 자리 = 0): number {
+  if (!Number.isFinite(값) || !Number.isInteger(자리) || 자리 < -10 || 자리 > 10) throw new Error("유한한 수와 -10~10 사이의 정수 자리가 필요합니다.");
+  return Math.round(값 * 10 ** 자리) / 10 ** 자리;
+}
+function 평균(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 평균을 구할 수 없습니다.");
+  return 합계(목록) / 목록.length;
+}
+function 최솟값(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 최솟값을 구할 수 없습니다.");
+  let 결과 = 목록[0]; for (const 항목 of 목록) if (항목 < 결과) 결과 = 항목;
+  return 결과;
+}
+function 최댓값(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 최댓값을 구할 수 없습니다.");
+  let 결과 = 목록[0]; for (const 항목 of 목록) if (항목 > 결과) 결과 = 항목;
+  return 결과;
+}
+function 정렬(값: readonly number[]): number[] { return [...값].sort((가, 나) => 가 - 나); }
+function 범위(시작: number, 끝?: number, 간격 = 1): number[] {
+  if (끝 === undefined) { 끝 = 시작; 시작 = 0; }
+  if (!Number.isFinite(시작) || !Number.isFinite(끝) || !Number.isFinite(간격) || 간격 === 0) throw new Error("범위에는 유한한 수와 0이 아닌 간격이 필요합니다.");
+  const 개수 = Math.max(0, Math.ceil((끝 - 시작) / 간격));
+  if (개수 > 100000) throw new Error("범위는 최대 100000개까지 만들 수 있습니다.");
+  return Array.from({ length: 개수 }, (_, 순서) => 시작 + 순서 * 간격);
+}
+`;
+
+export function compileSentences(source, { includeRuntime = true } = {}) {
+  const output = includeRuntime ? [sentenceRuntime] : [];
+  const indents = [0];
+  let needsIndent = false;
+  const lines = source.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    const raw = lines[index];
+    const text = raw.trim();
+    if (!text || text === '문장으로 시작' || text.startsWith('#')) continue;
+    const fail = message => { throw new SyntaxError(`${index + 1}행: ${message}`); };
+    if (/^\s*\t/.test(raw)) fail('들여쓰기는 탭 대신 공백을 사용하세요.');
+    const indent = raw.length - raw.trimStart().length;
+    if (needsIndent) {
+      if (indent <= indents.at(-1)) fail('블록 안의 문장을 들여써 주세요.');
+      indents.push(indent);
+    } else if (indent > indents.at(-1)) fail('예상하지 못한 들여쓰기입니다.');
+    while (indent < indents.at(-1)) { indents.pop(); output.push('}'); }
+    if (indent !== indents.at(-1)) fail('이전 블록과 들여쓰기를 맞춰 주세요.');
+    needsIndent = false;
+    let match;
+    if ((match = text.match(/^(.+\))를 정의한다:$/u))) {
+      // Unannotated parameters are intentionally dynamic, like Python.
+      const signature = match[1].replace(/\((.*)\)$/, (_, params) => '(' + params.split(',').filter(x => x.trim()).map(x => x.includes(':') ? x.trim() : `${x.trim()}: any`).join(', ') + ')');
+      output.push(`function ${signature} {`); needsIndent = true;
+    } else if ((match = text.match(/^각 (.+?)(?:을|를) (.+)에서:$/u))) {
+      if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(match[1])) fail('반복 변수 이름을 확인하세요.');
+      output.push(`for (const ${match[1]} of ${match[2]}) {`); needsIndent = true;
+    } else if ((match = text.match(/^만약 (.+) (?:이)?라면:$/u))) {
+      output.push(`if (${match[1]}) {`); needsIndent = true;
+    } else if ((match = text.match(/^아니고 (.+) (?:이)?라면:$/u))) {
+      if (output.at(-1) !== '}') fail('아니고 앞에는 조건 블록이 필요합니다.');
+      output.push(`else if (${match[1]}) {`); needsIndent = true;
+    } else if (text === '아니면:') {
+      if (output.at(-1) !== '}') fail('아니면 앞에는 조건 블록이 필요합니다.');
+      output.push('else {'); needsIndent = true;
+    } else if ((match = text.match(/^동안 (.+):$/u))) {
+      output.push(`while (${match[1]}) {`); needsIndent = true;
+    } else if ((match = text.match(/^(.+?)(?:은|는) (.+)이다$/u))) {
+      if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(match[1])) fail('변수 이름을 확인하세요.');
+      output.push(`let ${match[1]}${match[2].trim() === '[]' ? ': any[]' : ''} = ${match[2]};`);
+    } else if ((match = text.match(/^돌려주기(?: (.+))?$/u))) {
+      output.push(`return ${match[1] ?? ''};`);
+    } else if (text === '멈추기') output.push('break;');
+    else if (text === '계속하기') output.push('continue;');
+    else if (text.endsWith(':')) fail('지원하지 않는 블록 문장입니다.');
+    else output.push(text + (text.endsWith(';') ? '' : ';'));
+  }
+  if (needsIndent) throw new SyntaxError('마지막 블록에 실행할 문장이 필요합니다.');
+  while (indents.length > 1) { indents.pop(); output.push('}'); }
+  return output.join('\n');
+}

package/dist/transformer.d.ts

@@ -0,0 +1,2 @@
+/** Convert keyword-style or sentence-style .hgs source into TypeScript. */
+export function compileSource(source: string): string;

package/dist/transformer.js

@@ -0,0 +1,338 @@
+import ts from 'typescript';
+import { compileSentences, isSentenceSource, sentenceRuntime } from './sentences.js';
+
+const identifierCharRegex = /[\p{L}\p{N}_$]/u;
+
+const KEYWORD_TRANSFORMS = [
+  { match: "내보내기 기본내보내기", replacement: "export default", requiresBoundary: true },
+  { match: "비동기함수", replacement: "async function", requiresBoundary: true },
+  { match: "상수", replacement: "const", requiresBoundary: true },
+  { match: "변수", replacement: "let", requiresBoundary: true },
+  { match: "함수", replacement: "function", requiresBoundary: true },
+  { match: "반환", replacement: "return", requiresBoundary: true },
+  { match: "만약", replacement: "if", requiresBoundary: true },
+  { match: "아니면", replacement: "else", requiresBoundary: true },
+  { match: "반복", replacement: "for", requiresBoundary: true },
+  { match: "동안", replacement: "while", requiresBoundary: true },
+  { match: "실행", replacement: "do", requiresBoundary: true },
+  { match: "참", replacement: "true", requiresBoundary: true },
+  { match: "거짓", replacement: "false", requiresBoundary: true },
+  { match: "비어있음", replacement: "null", requiresBoundary: true },
+  { match: "정의안됨", replacement: "undefined", requiresBoundary: true },
+  { match: "가져오기", replacement: "import", requiresBoundary: true },
+  { match: "에서", replacement: "from", requiresBoundary: true },
+  { match: "프롬", replacement: "from", requiresBoundary: true },
+  { match: "오브", replacement: "of", requiresBoundary: true },
+  { match: "안에", replacement: "in", requiresBoundary: true },
+  { match: "내보내기", replacement: "export", requiresBoundary: true },
+  { match: "스위치", replacement: "switch", requiresBoundary: true },
+  { match: "선택", replacement: "switch", requiresBoundary: true },
+  { match: "케이스", replacement: "case", requiresBoundary: true },
+  { match: "경우", replacement: "case", requiresBoundary: true },
+  { match: "디폴트", replacement: "default", requiresBoundary: true },
+  { match: "기본", replacement: "default", requiresBoundary: true },
+  { match: "중단", replacement: "break", requiresBoundary: true },
+  { match: "멈춤", replacement: "break", requiresBoundary: true },
+  { match: "계속", replacement: "continue", requiresBoundary: true },
+  { match: "마침내", replacement: "finally", requiresBoundary: true },
+  { match: "타입", replacement: "type", requiresBoundary: true },
+  { match: "인터페이스", replacement: "interface", requiresBoundary: true },
+  { match: "구현", replacement: "implements", requiresBoundary: true },
+  { match: "확장", replacement: "extends", requiresBoundary: true },
+  { match: "열거형", replacement: "enum", requiresBoundary: true },
+  { match: "클래스", replacement: "class", requiresBoundary: true },
+  { match: "추상", replacement: "abstract", requiresBoundary: true },
+  { match: "공개", replacement: "public", requiresBoundary: true },
+  { match: "보호", replacement: "protected", requiresBoundary: true },
+  { match: "비공개", replacement: "private", requiresBoundary: true },
+  { match: "정적", replacement: "static", requiresBoundary: true },
+  { match: "읽기전용", replacement: "readonly", requiresBoundary: true },
+  { match: "얻기", replacement: "get", requiresBoundary: true },
+  { match: "설정", replacement: "set", requiresBoundary: true },
+  { match: "선언", replacement: "declare", requiresBoundary: true },
+  { match: "생성자", replacement: "constructor", requiresBoundary: true },
+  { match: "상위", replacement: "super", requiresBoundary: true },
+  { match: "이것", replacement: "this", requiresBoundary: true },
+  { match: "새로운", replacement: "new", requiresBoundary: true },
+  { match: "대기", replacement: "await", requiresBoundary: true },
+  { match: "시도", replacement: "try", requiresBoundary: true },
+  { match: "잡기", replacement: "catch", requiresBoundary: true },
+  { match: "던지기", replacement: "throw", requiresBoundary: true },
+  { match: "양보", replacement: "yield", requiresBoundary: true },
+  { match: "삭제", replacement: "delete", requiresBoundary: true },
+  { match: "타입오브", replacement: "typeof", requiresBoundary: true },
+  { match: "키오브", replacement: "keyof", requiresBoundary: true },
+  { match: "인퍼", replacement: "infer", requiresBoundary: true },
+  { match: "만족", replacement: "satisfies", requiresBoundary: true },
+  { match: "애즈", replacement: "as", requiresBoundary: true },
+  { match: "처럼", replacement: "as", requiresBoundary: true },
+  { match: "이즈", replacement: "is", requiresBoundary: true },
+  { match: "이다", replacement: "is", requiresBoundary: true },
+  { match: "무효", replacement: "void", requiresBoundary: true },
+  { match: "문자열", replacement: "string", requiresBoundary: true },
+  { match: "숫자", replacement: "number", requiresBoundary: true },
+  { match: "불리언", replacement: "boolean", requiresBoundary: true },
+  { match: "아무거나", replacement: "any", requiresBoundary: true },
+  { match: "배열", replacement: "Array", requiresBoundary: true },
+  { match: "레코드", replacement: "Record", requiresBoundary: true },
+  { match: "맵", replacement: "Map", requiresBoundary: true },
+  { match: "세트", replacement: "Set", requiresBoundary: true },
+  { match: "약한맵", replacement: "WeakMap", requiresBoundary: true },
+  { match: "약한세트", replacement: "WeakSet", requiresBoundary: true },
+  { match: "프로미스", replacement: "Promise", requiresBoundary: true },
+  { match: "객체", replacement: "Object", requiresBoundary: true },
+  { match: "날짜", replacement: "Date", requiresBoundary: true },
+  { match: "오류", replacement: "Error", requiresBoundary: true },
+  { match: "정규식", replacement: "RegExp", requiresBoundary: true },
+  { match: "제이슨", replacement: "JSON", requiresBoundary: true },
+  { match: "수학", replacement: "Math", requiresBoundary: true },
+  { match: "콘솔.출력", replacement: "console.log", requiresBoundary: true }
+];
+
+const transformsByFirst = new Map();
+for (const transform of KEYWORD_TRANSFORMS) {
+  const first = transform.match[0];
+  if (!transformsByFirst.has(first)) transformsByFirst.set(first, []);
+  transformsByFirst.get(first).push(transform);
+}
+
+function isIdentifierBoundary(source, index) {
+  if (index <= 0 || index >= source.length) {
+    return true;
+  }
+  const char = source[index - 1];
+  return !identifierCharRegex.test(char);
+}
+
+function isBoundaryAfter(source, index) {
+  if (index >= source.length) {
+    return true;
+  }
+  const char = source[index];
+  return !identifierCharRegex.test(char);
+}
+
+function tryApplyTransform(source, index) {
+  for (const transform of transformsByFirst.get(source[index]) ?? []) {
+    if (!source.startsWith(transform.match, index)) {
+      continue;
+    }
+    if (transform.requiresBoundary) {
+      const beforeOk = isIdentifierBoundary(source, index);
+      const afterOk = isBoundaryAfter(source, index + transform.match.length);
+      if (!beforeOk || !afterOk) {
+        continue;
+      }
+    }
+    return {
+      replacement: transform.replacement,
+      length: transform.match.length
+    };
+  }
+  return null;
+}
+
+function transformKeywords(source) {
+  let result = "";
+  let index = 0;
+  const modeStack = ["code"];
+  const templateExpressionStack = [];
+
+  while (index < source.length) {
+    const mode = modeStack[modeStack.length - 1];
+    const char = source[index];
+
+    if (mode === "code" || mode === "templateExpression") {
+      if (mode === "templateExpression") {
+        if (char === "}") {
+          const info = templateExpressionStack[templateExpressionStack.length - 1];
+          info.depth -= 1;
+          result += char;
+          index += 1;
+          if (info.depth === 0) {
+            templateExpressionStack.pop();
+            modeStack.pop();
+          }
+          continue;
+        }
+        if (char === "{") {
+          const info = templateExpressionStack[templateExpressionStack.length - 1];
+          info.depth += 1;
+          result += char;
+          index += 1;
+          continue;
+        }
+      }
+
+      if (char === "\"") {
+        modeStack.push("doubleQuote");
+        result += char;
+        index += 1;
+        continue;
+      }
+      if (char === "'") {
+        modeStack.push("singleQuote");
+        result += char;
+        index += 1;
+        continue;
+      }
+      if (char === "`") {
+        modeStack.push("template");
+        result += char;
+        index += 1;
+        continue;
+      }
+      if (char === "/") {
+        const next = source[index + 1];
+        if (next === "/") {
+          modeStack.push("lineComment");
+          result += "//";
+          index += 2;
+          continue;
+        }
+        if (next === "*") {
+          modeStack.push("blockComment");
+          result += "/*";
+          index += 2;
+          continue;
+        }
+      }
+
+      const transform = tryApplyTransform(source, index);
+      if (transform) {
+        result += transform.replacement;
+        index += transform.length;
+        continue;
+      }
+
+      result += char;
+      index += 1;
+      continue;
+    }
+
+    if (mode === "singleQuote") {
+      result += char;
+      index += 1;
+      if (char === "\\") {
+        if (index < source.length) {
+          result += source[index];
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "'") {
+        modeStack.pop();
+      }
+      continue;
+    }
+
+    if (mode === "doubleQuote") {
+      result += char;
+      index += 1;
+      if (char === "\\") {
+        if (index < source.length) {
+          result += source[index];
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "\"") {
+        modeStack.pop();
+      }
+      continue;
+    }
+
+    if (mode === "template") {
+      result += char;
+      index += 1;
+      if (char === "\\") {
+        if (index < source.length) {
+          result += source[index];
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "`") {
+        modeStack.pop();
+        continue;
+      }
+      if (char === "$" && source[index] === "{") {
+        result += "{";
+        modeStack.push("templateExpression");
+        templateExpressionStack.push({ depth: 1 });
+        index += 1;
+      }
+      continue;
+    }
+
+    if (mode === "lineComment") {
+      result += char;
+      index += 1;
+      if (char === "\n") {
+        modeStack.pop();
+      }
+      continue;
+    }
+
+    if (mode === "blockComment") {
+      result += char;
+      index += 1;
+      if (char === "*" && source[index] === "/") {
+        result += "/";
+        index += 1;
+        modeStack.pop();
+      }
+      continue;
+    }
+  }
+
+  return result;
+}
+
+// Scan tokens so literals, comments, and nested function bodies stay untouched.
+function fixClassMethods(source) {
+  if (!source.includes('class')) return source;
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, source);
+  const stack = [];
+  const edits = [];
+  let pendingClass = false;
+  let previous = ts.SyntaxKind.Unknown;
+  const templateDepths = [];
+  let braces = 0;
+  for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+    if (token === ts.SyntaxKind.CloseBraceToken && templateDepths.at(-1) === braces) {
+      token = scanner.reScanTemplateToken(false);
+      if (token === ts.SyntaxKind.TemplateTail) templateDepths.pop();
+      continue;
+    }
+    if (token === ts.SyntaxKind.TemplateHead) { templateDepths.push(braces); continue; }
+    if (token === ts.SyntaxKind.SingleLineCommentTrivia || token === ts.SyntaxKind.MultiLineCommentTrivia ||
+        token === ts.SyntaxKind.WhitespaceTrivia || token === ts.SyntaxKind.NewLineTrivia) continue;
+    if (token === ts.SyntaxKind.ClassKeyword) pendingClass = true;
+    if (token === ts.SyntaxKind.OpenBraceToken) {
+      stack.push(pendingClass ? 'class' : 'block');
+      pendingClass = false;
+      braces++;
+    } else if (token === ts.SyntaxKind.CloseBraceToken) {
+      stack.pop(); braces--;
+    } else if (token === ts.SyntaxKind.FunctionKeyword && stack.at(-1) === 'class' &&
+      [ts.SyntaxKind.OpenBraceToken, ts.SyntaxKind.CloseBraceToken, ts.SyntaxKind.SemicolonToken,
+       ts.SyntaxKind.AsyncKeyword, ts.SyntaxKind.PublicKeyword, ts.SyntaxKind.PrivateKeyword,
+       ts.SyntaxKind.ProtectedKeyword, ts.SyntaxKind.StaticKeyword].includes(previous)) {
+      const start = scanner.getTokenPos();
+      let end = scanner.getTextPos();
+      while (source[end] === ' ' || source[end] === '\t') end++;
+      edits.push([start, end]);
+    }
+    previous = token;
+  }
+  for (const [start, end] of edits.reverse()) source = source.slice(0, start) + source.slice(end);
+  return source;
+}
+
+export function compileSource(source) {
+  const sentenceMode = isSentenceSource(source);
+  if (sentenceMode) source = compileSentences(source, { includeRuntime: false });
+  const transformed = fixClassMethods(transformKeywords(source));
+  return sentenceMode ? sentenceRuntime + '\n' + transformed : transformed;
+}

package/examples/calculator.hgs

@@ -0,0 +1,18 @@
+문장으로 시작
+첫째는 24이다
+둘째는 6이다
+연산은 "나누기"이다
+
+계산(가, 나, 방식)를 정의한다:
+    만약 방식 == "더하기" 이라면:
+        돌려주기 가 + 나
+    아니고 방식 == "빼기" 이라면:
+        돌려주기 가 - 나
+    아니고 방식 == "곱하기" 이라면:
+        돌려주기 가 * 나
+    아니면:
+        만약 나 == 0 이라면:
+            돌려주기 "0으로 나눌 수 없습니다"
+        돌려주기 가 / 나
+
+출력("계산 결과:", 계산(첫째, 둘째, 연산))

package/examples/discount.hgs

@@ -0,0 +1,9 @@
+문장으로 시작
+가격은 32000이다
+할인율은 15이다
+만약 가격 < 0 || 할인율 < 0 || 할인율 > 100 이라면:
+    출력("가격은 0 이상, 할인율은 0~100 사이로 입력하세요")
+아니면:
+    할인액은 반올림(가격 * 할인율 / 100)이다
+    출력("할인액:", 할인액, "원")
+    출력("결제 금액:", 가격 - 할인액, "원")

package/examples/hello.hgs

@@ -0,0 +1,21 @@
+상수 이름 = "철수";
+변수 나이: 숫자 = 12;
+
+함수 인사(사람이름: 문자열): 문자열 {
+  반환 `안녕 ${사람이름}!`;
+}
+
+클래스 사람 {
+  이름: 문자열;
+  나이: 숫자;
+  생성자(이름: 문자열, 나이: 숫자) {
+    이것.이름 = 이름;
+    이것.나이 = 나이;
+  }
+
+  함수 소개(): 문자열 {
+    반환 `${이것.이름}(${이것.나이}) 입니다`;
+  }
+}
+
+콘솔.출력(인사(이름));

package/examples/math-library.hgs

@@ -0,0 +1,4 @@
+문장으로 시작
+더함(가: 숫자, 나: 숫자)를 정의한다:
+    돌려주기 가 + 나
+내보내기 { 더함 }

package/examples/scores.hgs

@@ -0,0 +1,9 @@
+문장으로 시작
+점수들은 [75, 92, 88, 64, 97]이다
+합격자들은 []이다
+각 점수를 점수들에서:
+    만약 점수 >= 80 이라면:
+        추가(합격자들, 점수)
+출력("합격 점수:", 정렬(합격자들))
+출력("평균 점수:", 합계(점수들) / 길이(점수들))
+출력("합격 인원:", 길이(합격자들))

package/examples/statistics.hgs

@@ -0,0 +1,10 @@
+문장으로 시작
+입력값은 "10, 20, 30, 40"이다
+목록은 []이다
+각 항목을 나누기(입력값, ",")에서:
+    추가(목록, 숫자로(항목))
+출력("개수:", 길이(목록))
+출력("합계:", 합계(목록))
+출력("평균:", 평균(목록))
+출력("최솟값:", 최솟값(목록))
+출력("최댓값:", 최댓값(목록))

package/examples/text.hgs

@@ -0,0 +1,9 @@
+문장으로 시작
+원문은 "  사과, 바나나, 사과, 포도  "이다
+단어들은 []이다
+각 조각을 나누기(다듬기(원문), ",")에서:
+    단어는 다듬기(조각)이다
+    만약 길이(단어) > 0 && !포함(단어들, 단어) 이라면:
+        추가(단어들, 단어)
+출력("중복 없이:", 잇기(단어들, " · "))
+출력("단어 수:", 길이(단어들))

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@uiwwsw/hangulscript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "한글 문장으로 작성하고 JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/transformer.d.ts",
+      "import": "./dist/transformer.js"
+    }
+  },
+  "bin": {
+    "ksc": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LANGUAGE.md",
+    "LICENSE",
+    "examples/*.hgs"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.js",
+    "prepublishOnly": "npm test && npm run build",
+    "test": "node --test",
+    "build:site": "node scripts/build-site.js",
+    "benchmark": "node scripts/benchmark.js"
+  },
+  "dependencies": {
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "hangul",
+    "korean",
+    "hgs",
+    "typescript",
+    "transpiler"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uiwwsw/hangulscript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uiwwsw/hangulscript/issues"
+  },
+  "homepage": "https://github.com/uiwwsw/hangulscript#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "types": "dist/index.d.ts"
+}