@uiwwsw/hangulscript 0.6.0 → 0.8.0

package/docs/guides/errors.md

@@ -0,0 +1,24 @@
+# 오류 읽고 고치기
+
+문법·타입 오류는 원본 `.hgs`의 파일 이름·행·열로 표시됩니다. VS Code에서는 Problems 패널과 밑줄, Vite에서는 개발 화면의 오류와 실패한 빌드, CLI에서는 실패 종료 코드로 확인합니다. 웹 데모의 오류 항목을 누르면 해당 위치로 이동합니다.
+
+```text
+main.hgs:1:1 [TS2322] 선언한 타입과 대입한 값의 타입을 확인하세요.
+```
+
+`값: 숫자는 "문자"이다`는 숫자 타입과 문자열 값이 달라 실패합니다. `값: 숫자는 42이다`처럼 고치세요.
+
+| 표시 | 뜻 | 확인할 내용 |
+| --- | --- | --- |
+| HGS1001 | 문장 또는 들여쓰기 오류 | 콜론·블록·지원 문법 |
+| TS2304 | 찾을 수 없는 이름 | 오타·선언·스코프 |
+| TS2307 | 찾을 수 없는 모듈 | 상대 경로·실제 파일·타입 선언 |
+| TS2322 | 대입 타입 불일치 | 변수 타입과 넣는 값 |
+| TS2339 | 없는 속성·메서드 | 대상 타입과 속성 이름 |
+| TS2345 | 인자 타입 불일치 | 함수에 넘긴 값의 타입 |
+| TS2554 | 인자 개수 불일치 | 필수 인자의 개수 |
+| TS7006 | 명시되지 않은 매개변수 타입 | 숫자·문자열 등 타입 |
+
+`any` 또는 `아무거나`는 타입 검사를 느슨하게 만듭니다. 빈 목록 `[]`의 기본 타입도 현재 `any[]`이므로 엄격히 검사하려면 `점수들: 목록<숫자>는 []이다`처럼 적으세요. 타입이 맞아도 0으로 나누기·잘못된 범위·사용자 규칙 위반은 별도의 실행 검사가 필요합니다.
+
+문자열 길이와 진단 열은 JavaScript UTF-16 기준입니다. `목록으로("문자열")`의 문자열 순회는 코드 포인트 기준입니다. 이모지나 결합 문자의 사용자 인식 글자 수와는 다를 수 있습니다.

package/docs/guides/modules.md

@@ -0,0 +1,28 @@
+# 모듈과 JavaScript로 배포하기
+
+관련 있는 함수를 `.hgs` 파일에 묶고 공개합니다. 아래 첫 코드는 `math.hgs`입니다.
+
+```hgs
+더함(가: 숫자, 나: 숫자)를 정의한다:
+    돌려주기 가 + 나
+더함을 공개한다
+```
+
+진입 파일 `main.hgs`에서 상대 경로로 가져옵니다.
+
+```hgs
+"./math.hgs"에서 { 더함 }을 가져온다
+출력(더함(2, 3))
+```
+
+```bash
+npx ksc run main.hgs
+node --import @uiwwsw/hangulscript/register main.hgs
+npx ksc build main.hgs --out-dir dist
+```
+
+직접 실행은 소스 옆에 생성물을 남기지 않습니다. 빌드는 진입 폴더 아래 HGS 의존성도 함께 만들며 import 경로를 `.js`로 바꿉니다. `dist/main.js`, `dist/main.d.ts`, `dist/math.js`, `dist/math.d.ts`가 생성됩니다. 진입 폴더 밖 HGS 의존성은 오류로 처리하므로 공통 상위 폴더에 진입 파일을 두세요.
+
+JavaScript와 TypeScript에서는 생성된 `.js`를 가져옵니다. TypeScript는 인접한 `.d.ts`를 읽습니다. 출력은 ESM이므로 소비 프로젝트에 `"type": "module"`을 설정합니다. 기존 JS 파일과 자산은 HGS 빌드가 복사하지 않습니다.
+
+`ksc --check main.hgs`는 타입만 검사합니다. `ksc --typescript main.hgs`는 내부 변환 TypeScript를 확인하는 옵션이며 별도 소스 문법이 아닙니다. 원본 디버깅 소스맵·자동 빌드 감시 CLI·독립 네이티브 바이너리 출력은 아직 제공하지 않습니다.

package/docs/guides/start.md

@@ -0,0 +1,22 @@
+# 첫 프로그램 만들기
+
+한글스크립트는 `.hgs` 파일에 문장형 코드와 들여쓰기를 작성합니다. 시작 표기는 필요하지 않습니다. Node.js 20.19 이상을 설치하고 아래 순서대로 실행하세요.
+
+```bash
+npm install --save-dev @uiwwsw/hangulscript@^0.8.0
+npx ksc run main.hgs
+```
+
+`main.hgs`에 다음을 저장합니다.
+
+```hgs
+점수들은 [75, 92, 88]이다
+각 점수를 점수들에서:
+    만약 점수 >= 80 이라면:
+        출력(점수)
+출력("평균:", 평균(점수들))
+```
+
+배포에는 `npx ksc build main.hgs --out-dir dist`를 사용합니다. JavaScript와 타입 선언 `.d.ts`가 함께 생성됩니다. 생성된 `.js`를 Node에서 실행할 프로젝트에는 package.json의 `"type": "module"`을 설정하세요.
+
+설치 없이 확인하려면 [실행 화면](/#playground)을 사용하세요. 공유한 코드는 자동 실행하지 않습니다. 브라우저는 격리된 실행 환경에서 최대 2초 동안 동작합니다.

package/docs/guides/writing.md

@@ -0,0 +1,29 @@
+# 뜻이 분명한 문장으로 개발하기
+
+잘 쓴 코드에는 좋은 글과 닮은 점이 있습니다. 대상의 이름이 분명하고, 행동의 이유가 있으며, 앞에서 정한 규칙이 뒤에서도 지켜집니다. 한글스크립트에서는 이를 이름·타입·조건·결과·모듈로 표현합니다.
+
+- 인물과 사물: 자료의 이름과 타입을 정합니다.
+- 세계의 규칙: 허용하는 값과 불변 조건을 분명히 씁니다.
+- 사건: 함수가 무엇을 받아 무엇을 돌려주는지 정합니다.
+- 장면: 관련 있는 함수를 모듈로 묶습니다.
+- 앞뒤의 일관성: 타입 검사와 테스트로 확인합니다.
+
+```hgs
+할인후금액(가격: 숫자, 할인율: 숫자)를 정의한다:
+    확인한다(Number.isFinite(가격) && 가격 >= 0, "가격은 유한한 0 이상의 수입니다")
+    확인한다(Number.isFinite(할인율) && 할인율 >= 0 && 할인율 <= 100, "할인율은 0~100입니다")
+    결과는 가격 - 반올림(가격 * 할인율 / 100)이다
+    확인한다(결과 >= 0, "결제 금액은 음수가 아닙니다")
+    돌려주기 결과
+
+확인한다(할인후금액(10000, 20) === 8000, "20% 할인 계산을 확인합니다")
+출력(할인후금액(10000, 20))
+```
+
+이 예제는 입력 조건·처리·결과 조건을 코드에 남깁니다. 타입 검사는 숫자 자리에 문자열을 전달하는 오류를 찾고, `확인한다`는 실행 중 조건 위반을 찾습니다. 모든 경우의 올바름을 수학적으로 증명하는 기능은 아닙니다.
+
+## AI API가 꼭 필요한가요?
+
+필요하지 않습니다. 정해진 문법, 타입, 조건 검사, 명시적인 예외, 실행 가능한 예제만으로도 문장이 명확할수록 검사 가능한 내용을 늘릴 수 있습니다. 현재 언어는 소설이나 임의의 산문을 자동으로 실행하지 않습니다.
+
+자유로운 글에서 프로그램 후보를 제안하는 보조 기능은 향후 AI로 만들 수 있습니다. 로컬 모델도 가능하며 외부 API만이 방법은 아닙니다. 다만 생성된 코드에는 같은 컴파일·타입·테스트 검증이 필요합니다. 핵심 문법과 실행은 AI 서비스 없이 동작합니다.

package/docs/publishing.md

@@ -0,0 +1,13 @@
+# npm 자동 게시
+
+저장소 Actions Secret **NPM_TOKEN**을 사용합니다. 토큰은 소스·워크플로 본문·.env 파일에 넣지 않습니다. 현재 로그인에 쓰는 개인 세션 토큰을 재사용하지 말고 npm에서 이 패키지에만 권한을 주는 granular access token을 발급하세요.
+
+1. npm Access Tokens에서 만료 기간을 정하고 `@uiwwsw/hangulscript`에만 읽기·쓰기 권한을 부여합니다. 무인 게시에는 토큰의 게시용 2FA 우회 권한과 패키지의 해당 토큰 게시 허용 정책이 모두 맞아야 합니다. 계정 전체 2FA를 끄지 않습니다.
+2. GitHub 저장소 Settings → Secrets and variables → Actions → New repository secret에서 이름을 `NPM_TOKEN`으로 등록합니다. 토큰 값은 채팅·이슈·문서에 붙이지 않습니다.
+3. package.json 버전을 높여 커밋하고 동일한 `v버전` 태그의 GitHub Release를 게시합니다. 이미 존재하는 버전은 다시 게시할 수 없습니다.
+4. `Publish npm package` 작업이 태그·패키지명·시크릿 존재를 검사하고 테스트·빌드 후 생성한 tarball을 provenance와 함께 게시합니다. 수동 실행은 동일한 릴리스 태그를 입력합니다. 시험판은 `next`, 정식 버전은 `latest` 태그를 사용합니다.
+5. npm 공개 버전과 다운로드 체크섬을 확인합니다. 토큰이 만료되면 전용 토큰을 교체하고 같은 시크릿을 갱신합니다.
+
+워크플로는 PR·브랜치 push로 게시되지 않습니다. npm 게시 권한은 게시 단계에만 전달하며 출력하지 않습니다. 토큰을 등록하지 않은 상태에서는 명확한 오류로 중단합니다.
+
+토큰 보관을 없애려면 npm Trusted Publishing(OIDC)을 별도로 구성할 수도 있습니다. [npm 공식 토큰 안내](https://docs.npmjs.com/creating-and-viewing-access-tokens/) · [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)

package/docs/support.md

@@ -0,0 +1,44 @@
+# 지원 범위와 호환성
+
+한글스크립트는 명시된 한국어 문법을 JavaScript ES 모듈로 컴파일합니다. 임의의 자연어를 추측하지 않으며 별도 시작 표기는 사용하지 않습니다. 이 문서는 0.8.0 언어 패키지와 0.3.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.8.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가 기본 내장 언어로 채택하는 것은 별개입니다.
+
+0.8.0은 목록·집합·사전·복사·정렬 등을 포함한 61개 한글 함수를 제공합니다. 전체 JavaScript API의 한글 별칭, 데이터베이스·네트워크·GUI 프레임워크 전체를 제공한다는 뜻은 아닙니다. 지원하지 않는 기능은 기존 JS/TS 생태계와 연결하거나 별도 구현해야 합니다. [표준 기능 참조](https://hangulscript.vercel.app/docs/standard-library/)에서 제공 범위를 확인하세요.

package/examples/collections.hgs

@@ -0,0 +1,19 @@
+점수들은 [88, 92, 75, 88]이다
+점수순은 점수들을 내림차순으로 정렬한 값이다
+고유값은 점수들에서 중복을 제거한 값이다
+통과한값은 골라내기(점수들, 점수 => 점수 >= 80)이다
+
+재고: 사전<문자열, 숫자>는 사전()이다
+사전에담기(재고, "사과", 3)
+사전에담기(재고, "배", 5)
+
+원본은 [{ 점수: 10 }]이다
+얕은복사본은 원본을 얕게 복사한 값이다
+깊은복사본은 원본을 깊게 복사한 값이다
+얕은복사본[0].점수 = 20
+
+확인한다(원본[0].점수 === 20, "얕은 복사는 안쪽 참조를 공유합니다")
+확인한다(깊은복사본[0].점수 === 10, "깊은 복사는 안쪽 값도 복제합니다")
+출력("정렬:", 점수순, "중복 제거:", 고유값, "통과:", 통과한값)
+출력("재고:", 항목목록(재고))
+출력("원본과 깊은 복사본:", 원본[0].점수, 깊은복사본[0].점수)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uiwwsw/hangulscript",
-  "version": "0.6.0",
-  "description": "한글 문장으로 작성하고 JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어",
+  "version": "0.8.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,13 +69,16 @@
   },
   "homepage": "https://github.com/uiwwsw/hangulscript#readme",
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0"
+    "@vscode/test-electron": "^3.1.0",
+    "@vscode/vsce": "^4.0.0",
+    "esbuild": "^0.25.0",
+    "marked": "^18.1.1"
   },
   "types": "dist/index.d.ts"
 }