@uiwwsw/hangulscript 0.5.0 → 0.7.0

package/docs/frameworks.md

@@ -0,0 +1,152 @@
+# React·Vue에서 한글스크립트 사용하기
+
+이 가이드는 `@uiwwsw/hangulscript@0.7.0` 문법과 공통 Vite 플러그인을 사용합니다.
+화면과 상태는 React/Vue로 만들고 계산·조건·검증 함수를 `.hgs`에 작성합니다.
+데모의 `숫자입력`·`버튼`·`보여주기`는 데모 UI 실행 환경의 API이며 React/Vue 컴포넌트로 자동 변환되지 않습니다.
+
+## 완성된 예제를 먼저 실행하기
+
+Node.js 24에서 검증했습니다. 예제의 Vite는 Node.js `^20.19.0 || >=22.12.0`을 요구합니다.
+
+```bash
+git clone https://github.com/uiwwsw/hangulscript.git
+cd hangulscript/examples/react-vite
+npm ci
+npm run dev
+```
+
+Vue는 같은 저장소의 `examples/vue-vite`에서 `npm ci`와 `npm run dev`를 실행하세요.
+터미널에 표시된 localhost 주소를 열고 가격 10000, 할인율 20을 입력한 뒤 **계산하기**를 누르면 결제 금액 8,000원이 표시됩니다.
+개발 서버는 loopback에서 실행하며, 포트가 사용 중이면 터미널에 표시된 실제 주소를 사용하세요.
+배포할 정적 파일은 각 예제에서 `npm run build`로 만들고 `npm run preview`로 확인합니다.
+
+- [React 전체 소스](../examples/react-vite)
+- [Vue 전체 소스](../examples/vue-vite)
+
+## 기존 Vite 프로젝트에 설치하기
+
+```bash
+npm install --save-dev @uiwwsw/hangulscript@^0.7.0
+```
+
+React/Vue와 해당 Vite 플러그인은 기존 프로젝트에 설치돼 있다고 가정합니다.
+새 프로젝트는 위의 완성된 예제를 사용할 수 있습니다.
+
+React의 `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import hangulscript from '@uiwwsw/hangulscript/vite';
+
+export default defineConfig({ plugins: [hangulscript(), react()] });
+```
+
+Vue의 `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import hangulscript from '@uiwwsw/hangulscript/vite';
+
+export default defineConfig({ plugins: [hangulscript(), vue()] });
+```
+
+## 공통 로직 작성하기
+
+두 예제의 `src/discount.hgs`는 동일합니다. 함수와 조건을 한글 문장으로 작성하고 ESM `export`로 내보냅니다.
+
+```text
+결제금액(가격: 숫자, 할인율: 숫자)를 정의한다:
+    만약 !Number.isFinite(가격) || !Number.isFinite(할인율) || 가격 < 0 || 할인율 < 0 || 할인율 > 100 이라면:
+        돌려주기 "가격은 0 이상, 할인율은 0~100 사이로 입력하세요"
+    돌려주기 가격 - 반올림(가격 * 할인율 / 100)
+
+결제금액을 공개한다
+```
+
+## React에서 호출하기
+
+`src/main.jsx`에서 함수를 가져와 submit 이벤트에 연결합니다. 입력과 결과 상태는 React가 관리합니다.
+
+```jsx
+import { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { 결제금액 } from './discount.hgs';
+import './style.css';
+
+function App() {
+  const [가격, 가격변경] = useState('10000');
+  const [할인율, 할인율변경] = useState('20');
+  const [결과, 결과변경] = useState(null);
+  function 계산(event) {
+    event.preventDefault();
+    결과변경(결제금액(Number(가격), Number(할인율)));
+  }
+  return <main>
+    <h1>React + 한글스크립트</h1>
+    <p>화면은 React, 계산과 검증은 discount.hgs에서 처리합니다.</p>
+    <form onSubmit={계산}>
+      <label>가격 (원)<input type="number" min="0" required value={가격} onChange={e => 가격변경(e.target.value)} /></label>
+      <label>할인율 (%)<input type="number" min="0" max="100" step="any" required value={할인율} onChange={e => 할인율변경(e.target.value)} /></label>
+      <button type="submit">계산하기</button>
+    </form>
+    <output aria-live="polite">{결과 === null ? '입력 후 계산하기를 눌러 주세요.' : typeof 결과 === 'number' ? `결제 금액: ${결과.toLocaleString('ko-KR')}원` : 결과}</output>
+  </main>;
+}
+createRoot(document.getElementById('app')).render(<App />);
+```
+
+## Vue에서 호출하기
+
+`src/App.vue`에서 같은 함수를 가져와 submit 이벤트에 연결합니다. 반응형 상태는 Vue가 관리합니다.
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { 결제금액 } from './discount.hgs';
+const 가격 = ref(10000);
+const 할인율 = ref(20);
+const 결과 = ref(null);
+function 계산() {
+  결과.value = 결제금액(Number(가격.value), Number(할인율.value));
+}
+</script>
+
+<template>
+  <main>
+    <h1>Vue + 한글스크립트</h1>
+    <p>화면은 Vue, 계산과 검증은 discount.hgs에서 처리합니다.</p>
+    <form @submit.prevent="계산">
+      <label>가격 (원)<input v-model="가격" type="number" min="0" required /></label>
+      <label>할인율 (%)<input v-model="할인율" type="number" min="0" max="100" step="any" required /></label>
+      <button type="submit">계산하기</button>
+    </form>
+    <output aria-live="polite">{{ 결과 === null ? '입력 후 계산하기를 눌러 주세요.' : typeof 결과 === 'number' ? `결제 금액: ${결과.toLocaleString('ko-KR')}원` : 결과 }}</output>
+  </main>
+</template>
+```
+
+## TypeScript 프로젝트와 빌드 범위
+
+| 방식 | 제공 범위 | 적합한 용도 |
+| --- | --- | --- |
+| Vite 플러그인으로 `.hgs` import | JavaScript 변환, Vite 개발 서버·빌드 연동 | React/Vue JavaScript 프로젝트 |
+| `ksc build` 후 `.js` import | 타입 검사, JavaScript와 `.d.ts` 생성 | TypeScript 프로젝트·라이브러리 |
+| 온라인 데모의 화면 함수 | 격리 실행, 입력창·버튼·결과 카드 | 설치 없는 도구 만들기·코드 공유 |
+
+0.7.0부터 Vite 플러그인은 구문과 타입을 검사하고 오류가 있으면 빌드를 중단합니다. 선언 생성·디버깅용 원본 `.hgs` 소스맵은 제공하지 않습니다.
+TypeScript에서 `.hgs` 파일을 직접 가져오면 모듈 타입을 찾지 못할 수 있습니다.
+외부 TypeScript 소비자에게 선언을 제공하려면 다음처럼 빌드한 `.js`를 가져오세요. 인접한 `.d.ts`를 TypeScript가 읽습니다.
+
+```bash
+npx ksc build src/discount.hgs
+```
+
+```ts
+import { 결제금액 } from './discount.js';
+const 결과 = 결제금액(10000, 20); // number | string
+```
+
+이 방식은 `.hgs`를 수정할 때 다시 빌드해야 합니다. 명시적인 타입과 추론 가능한 값은 검사하며, `any` 값에 대한 검사는 제한됩니다.
+Next.js·Webpack처럼 Vite를 사용하지 않는 환경에서도 미리 만든 `.js`·`.d.ts`를 가져오는 방식을 사용할 수 있습니다. 전용 Next.js·Webpack 플러그인은 제공하지 않습니다.

package/docs/support.md

@@ -0,0 +1,42 @@
+# 지원 범위와 호환성
+
+한글스크립트는 명시된 한국어 문법을 JavaScript ES 모듈로 컴파일합니다. 임의의 자연어를 추측하지 않으며 별도 시작 표기는 사용하지 않습니다. 이 문서는 0.7.0 언어 패키지와 0.2.0 VS Code 확장의 지원 계약입니다.
+
+| 환경 | 지원 내용 | 검증 |
+| --- | --- | --- |
+| Node.js 20.19 이상 | `ksc run`, JS + `.d.ts` 빌드, `.hgs` 모듈 import | Node 22·24 CI, 실행 통합 테스트 |
+| React·Vue + Vite | `.hgs` import, 개발·프로덕션 타입 오류 차단 | React JSX·Vue SFC 예제 빌드 |
+| VS Code 데스크톱 1.90 이상 | 문법 강조, 들여쓰기, 포맷, 진단, 타입 정보, 정의로 이동, 스코프 자동 완성 | 실제 Extension Host 통합 테스트 |
+| 웹 데모 | 타입 검사, 격리 실행, 입력·버튼 UI, 공유 | 별도 브라우저 검사기 테스트 |
+| JavaScript·TypeScript 소비자 | 생성된 `.js`와 `.d.ts` import | ESM 실행·선언 생성 테스트 |
+
+## Node에서 사용하기
+
+```bash
+npm install @uiwwsw/hangulscript@^0.7.0
+npx ksc run src/main.hgs
+# 또는 Node의 등록 진입점으로 직접 로드
+node --import @uiwwsw/hangulscript/register src/main.hgs
+# 배포 파일 생성
+npx ksc build src/main.hgs --out-dir dist
+```
+
+`ksc run`과 Node 등록 진입점은 `.hgs` 상대 import를 직접 읽고 검사합니다. 소스 옆에 생성물을 남기지 않습니다. 일반 Node 코드와 마찬가지로 파일·네트워크 권한을 가지므로 신뢰하는 코드에 사용하세요.
+
+`ksc build`는 진입 파일과 그 폴더 아래의 `.hgs` 의존성을 함께 빌드하고 디렉터리 구조를 유지합니다. `.hgs` import는 `.js`로 바뀝니다. 진입 폴더 밖의 HGS 의존성은 오류로 처리하므로 공통 상위 폴더에 진입 파일을 두세요. 생성된 `.js`는 ESM이므로 소비 프로젝트 `package.json`에 `"type": "module"`을 설정하세요.
+
+Vite가 아닌 환경에서 `.hgs` 파일을 바로 가져오려면 해당 로더가 필요합니다. 미리 생성한 `.js`·`.d.ts`는 일반 JS/TS 모듈로 사용할 수 있습니다. 상대 경로의 기존 JavaScript 파일·정적 자산은 HGS 빌드가 복사하지 않습니다.
+
+## 타입과 오류
+
+기본 검사는 strict 모드입니다. 가장 가까운 `tsconfig.json`의 `compilerOptions`와 `extends`를 읽습니다. 타입 해석을 위한 `types`, `typeRoots`, `paths`, `lib` 등을 사용할 수 있습니다. Node API 타입이 필요하면 프로젝트에 `@types/node`를 설치하고 `compilerOptions.types`에 `"node"`를 추가하세요. 파일 선택은 HGS 진입 파일과 import 그래프로 결정됩니다. 출력 형식은 ESM/ES2022, JS + 선언으로 고정하며 `noEmit`, `outDir` 등 출력 옵션은 CLI 설정이 우선합니다.
+
+함수 매개변수에 타입을 적으면 잘못된 인자 타입·개수·존재하지 않는 속성을 검사합니다. `any`를 지정한 값은 엄격한 검사를 우회합니다. 외부 JavaScript 모듈은 대응하는 타입 선언이 있어야 정확히 검사됩니다. 브라우저 데모는 로컬 tsconfig·Node API·외부 모듈을 읽지 않습니다.
+
+진단은 원본 HGS 행과 UTF-16 열을 사용합니다. 변환 과정에서 새로 생긴 토큰의 정확한 열을 찾을 수 없으면 해당 문장의 시작 위치를 사용합니다. 디버거용 소스맵과 실행 중 스택 추적의 원본 위치 변환은 아직 제공하지 않습니다.
+
+## 편집기 기능과 배포
+
+[VS Code 설치 및 기능 안내](../extensions/vscode/README.md)를 참고하세요. 확장은 컴파일러와 같은 저장소에서 관리하며 독립 버전으로 배포합니다. 편집기 검사는 Worker에서 실행하며 사용자 코드는 실행하지 않습니다. 자동 완성은 스코프의 이름과 스니펫을 제공합니다. 전체 속성 자동 완성, 자동 import, 이름 변경, 디버거, vscode.dev는 아직 지원하지 않습니다.
+
+0.x에서는 문법의 호환성을 깨는 변경을 minor 버전에서만 진행하고 변경 내역·마이그레이션을 안내합니다. patch 버전은 호환되는 수정에 사용합니다. 1.0은 별도의 문법 동결과 호환성 검증을 거쳐 결정합니다. 사용자용 확장을 Marketplace에 게시하는 것과 Microsoft가 기본 내장 언어로 채택하는 것은 별개입니다.

package/examples/calculator-ui.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 첫째는 숫자입력("첫 번째 수", 24)이다
 둘째는 숫자입력("두 번째 수", 6)이다
 연산은 선택입력("연산", ["더하기","빼기","곱하기","나누기"], "나누기")이다

package/examples/calculator.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 첫째는 24이다
 둘째는 6이다
 연산은 "나누기"이다

package/examples/discount-ui.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 가격은 숫자입력("가격 (원)", 32000)이다
 할인율은 숫자입력("할인율 (%)", 15)이다
 

package/examples/discount.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 가격은 32000이다
 할인율은 15이다
 만약 가격 < 0 || 할인율 < 0 || 할인율 > 100 이라면:

package/examples/hello.hgs

@@ -1,21 +1,6 @@
-상수 이름 = "철수";
-변수 나이: 숫자 = 12;
+이름은 "세상"이다
 
-함수 인사(사람이름: 문자열): 문자열 {
-  반환 `안녕 ${사람이름}!`;
-}
+인사(누구: 문자열)를 정의한다:
+    돌려주기 "안녕, " + 누구 + "!"
 
-클래스 사람 {
-  이름: 문자열;
-  나이: 숫자;
-  생성자(이름: 문자열, 나이: 숫자) {
-    이것.이름 = 이름;
-    이것.나이 = 나이;
-  }
-
-  함수 소개(): 문자열 {
-    반환 `${이것.이름}(${이것.나이}) 입니다`;
-  }
-}
-
-콘솔.출력(인사(이름));
+출력(인사(이름))

package/examples/math-library.hgs

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

package/examples/scores.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 점수들은 [75, 92, 88, 64, 97]이다
 합격자들은 []이다
 각 점수를 점수들에서:

package/examples/statistics-ui.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 입력값은 글자입력("쉼표로 구분한 숫자", "10, 20, 30, 40")이다
 
 "계산하기" 버튼을 누르면:

package/examples/statistics.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 입력값은 "10, 20, 30, 40"이다
 목록은 []이다
 각 항목을 나누기(입력값, ",")에서:

package/examples/text-ui.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 원문은 글자입력("정리할 문장", "  사과, 바나나, 사과, 포도  ")이다
 
 "정리하기" 버튼을 누르면:

package/examples/text.hgs

@@ -1,4 +1,3 @@
-문장으로 시작
 원문은 "  사과, 바나나, 사과, 포도  "이다
 단어들은 []이다
 각 조각을 나누기(다듬기(원문), ",")에서:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uiwwsw/hangulscript",
-  "version": "0.5.0",
-  "description": "한글 문장으로 작성하고 JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어",
+  "version": "0.7.0",
+  "description": "한글 문장으로 작성하고 JavaScript와 타입 선언으로 배포하는 프로그래밍 언어",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,15 @@
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
+    },
+    "./formatter": {
+      "types": "./dist/formatter.d.ts",
+      "import": "./dist/formatter.js"
+    },
+    "./register": "./dist/register.js",
+    "./editor": {
+      "types": "./dist/editor.d.ts",
+      "import": "./dist/editor.js"
     }
   },
   "bin": {
@@ -27,14 +36,19 @@
     "README.md",
     "LANGUAGE.md",
     "LICENSE",
-    "examples/*.hgs"
+    "examples/*.hgs",
+    "docs",
+    "CHANGELOG.md"
   ],
   "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"
+    "benchmark": "node scripts/benchmark.js",
+    "build:vscode": "node scripts/build-vscode.js",
+    "package:vscode": "npm run build:vscode && cd extensions/vscode && vsce package --no-dependencies",
+    "test:vscode": "npm run build:vscode && node scripts/run-editor-qa.js"
   },
   "dependencies": {
     "typescript": "^5.4.0"
@@ -55,12 +69,14 @@
   },
   "homepage": "https://github.com/uiwwsw/hangulscript#readme",
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@vscode/test-electron": "^3.1.0",
+    "@vscode/vsce": "^4.0.0",
     "esbuild": "^0.25.0"
   },
   "types": "dist/index.d.ts"