@uiwwsw/hangulscript 0.6.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/README.md

@@ -3,12 +3,12 @@
 [![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/) · [React·Vue 사용법](docs/frameworks.md) · [문법 명세](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)
 
 ```text
 점수들은 [75, 92, 88]이다
@@ -18,7 +18,7 @@ TypeScript의 타입 검사를 결합합니다. 소스 확장자는 **`.hgs`**
 출력("평균:", 평균(점수들))
 ```
 
-문장형은 실험판입니다. 정해진 한국어 문법을 파싱하며, 임의의 자연어를 추측해 실행하지 않습니다.
+정해진 한국어 문법을 파싱하며, 임의의 자연어를 추측해 실행하지 않습니다.
 Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습니다.
 
 ## 지금 만들 수 있는 것
@@ -39,7 +39,7 @@ Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습
 
 ## 설치
 
-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
@@ -235,7 +235,7 @@ Vite 연동을 제공합니다. 독립 AST·원본 `.hgs` 소스맵·LSP·모듈
 
 [MIT](LICENSE)
 
-## 이름과 확장자 이전 (0.4)
+## 이름과 확장자
 
 제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
 0.6부터 소스 확장자는 `.hgs`만 지원하며 키워드형과 시작 표기를 제거했습니다. 기존 코드는 [문법 명세](LANGUAGE.md)의 문장형으로 옮겨야 합니다.
@@ -270,7 +270,7 @@ HTML·이벤트 핸들러 문자열을 삽입하지 않습니다.
 **0.6.0 이상**의 공통 Vite 플러그인을 사용합니다. React/Vue의 화면과 상태 관리에 한글스크립트 계산·검증 함수를 연결할 수 있습니다.
 
 ```bash
-npm install --save-dev @uiwwsw/hangulscript@^0.6.0
+npm install --save-dev @uiwwsw/hangulscript@^0.7.0
 ```
 
 ```js
@@ -303,5 +303,15 @@ console.log(결제금액(10000, 20)); // 8000
 - [온라인 연동 안내](https://hangulscript.vercel.app/#frameworks)
 
 예제는 Node.js `^20.19.0 || >=22.12.0`이 필요하며 Node.js 24에서 검증했습니다.
-Vite 플러그인은 타입 검사·선언 생성·소스맵을 제공하지 않습니다. TypeScript 프로젝트는 `ksc build`로 생성한 `.js`와 `.d.ts`를 가져오는 방식이 적합합니다.
+**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';
 
@@ -15,7 +15,7 @@ function usage() {
   --typescript           변환된 TypeScript 확인용 출력
   -h, --help             도움말
 
-문장형은 실험판입니다. run은 신뢰하는 로컬 코드만 실행하세요.`);
+run은 신뢰하는 로컬 코드만 실행하세요.`);
 }
 
 async function main() {
@@ -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)));

package/dist/diagnostics.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+
+const hints = {
+  2304: '이름을 먼저 선언했는지 확인하세요.',
+  2307: '모듈 경로와 파일이 있는지 확인하세요.',
+  2322: '선언한 타입과 대입한 값의 타입을 확인하세요.',
+  2339: '이 값에 해당 속성이나 메서드가 있는지 확인하세요.',
+  2345: '함수에 전달한 값의 타입을 확인하세요.',
+  2554: '함수에 전달하는 인자의 개수를 확인하세요.',
+  7006: '공개 함수의 매개변수 타입을 명시하세요.'
+};
+
+export class HangulScriptError extends Error {
+  constructor(diagnostics) {
+    super(formatSourceDiagnostics(diagnostics));
+    this.name = 'HangulScriptError';
+    this.diagnostics = diagnostics;
+  }
+}
+
+export function syntaxDiagnostic(error, source, filePath) {
+  const lines = source.split(/\r?\n/);
+  const match = error.message.match(/^(\d+)행: /);
+  const line = match ? Number(match[1]) : Math.max(1, lines.findLastIndex(line => line.trim()) + 1);
+  const text = lines[line - 1] ?? '';
+  return { filePath, line, column: text.length - text.trimStart().length + 1, length: Math.max(1, text.trim().length), code: 'HGS1001', message: error.message.replace(/^\d+행: /, ''), severity: 'error' };
+}
+
+export function mapDiagnostic(diagnostic, documents) {
+  const file = diagnostic.file;
+  const position = file && diagnostic.start !== undefined ? file.getLineAndCharacterOfPosition(diagnostic.start) : { line: 0, character: 0 };
+  const document = file && documents.get(file.fileName);
+  let line = position.line + 1;
+  let column = position.character + 1;
+  let length = diagnostic.length ?? 1;
+  if (document) {
+    line = document.lineMap[position.line] || 1;
+    const original = document.source.split(/\r?\n/)[line - 1] ?? '';
+    const token = file.text.slice(diagnostic.start, diagnostic.start + length);
+    const generatedLine = file.text.split('\n')[position.line] ?? '';
+    const occurrence = token ? generatedLine.slice(0, position.character).split(token).length - 1 : 0;
+    let found = -1;
+    for (let i = 0; i <= occurrence; i++) {
+      const next = original.indexOf(token, found + 1);
+      if (next < 0) break;
+      found = next;
+    }
+    column = found >= 0 ? found + 1 : original.length - original.trimStart().length + 1;
+    length = Math.max(1, Math.min(length, original.length - column + 1));
+  }
+  const detail = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+  return {
+    filePath: document?.filePath ?? file?.fileName ?? 'input.hgs', line, column, length,
+    code: diagnostic.code, message: hints[diagnostic.code] ? `${hints[diagnostic.code]}\n${detail}` : detail,
+    severity: diagnostic.category === ts.DiagnosticCategory.Error ? 'error' : 'warning'
+  };
+}
+
+export function formatSourceDiagnostics(diagnostics) {
+  return diagnostics.map(d => `${d.filePath}:${d.line}:${d.column} [${typeof d.code === 'number' ? 'TS' : ''}${d.code}] ${d.message}`).join('\n');
+}

package/dist/editor.d.ts

@@ -0,0 +1,5 @@
+import type { CheckSettings } from './index.js';
+export interface EditorLocation { filePath: string; line: number; column: number; length: number; }
+export interface EditorInspection { hover?: string; definitions: EditorLocation[]; completions: { name: string; detail: string }[]; }
+/** One-based UTF-16 positions. Does not execute source. */
+export function inspectSource(source: string, filePath: string, line: number, column: number, settings?: CheckSettings): EditorInspection;

package/dist/editor.js

@@ -0,0 +1,50 @@
+import ts from 'typescript';
+import path from 'node:path';
+import { analyzeSource } from './checker.js';
+import { mapDiagnostic } from './diagnostics.js';
+
+/** One-based source positions; analysis only, never executes user code. */
+export function inspectSource(source, filePath, line, column, settings = {}) {
+  const analysis = analyzeSource(source, filePath, settings);
+  const file = analysis.program.getSourceFile(analysis.virtualRoot);
+  const document = analysis.documents.get(analysis.virtualRoot);
+  if (!file || !document) return { completions: [], definitions: [] };
+  let target = file;
+  let matched;
+  const original = source.split(/\r?\n/)[line - 1] ?? '';
+  const visit = node => {
+    if (ts.isIdentifier(node)) {
+      const pos = file.getLineAndCharacterOfPosition(node.getStart(file));
+      if (document.lineMap[pos.line] === line) {
+        target = node;
+        const generatedLine = file.text.split('\n')[pos.line];
+        const occurrence = generatedLine.slice(0, pos.character).split(node.text).length - 1;
+        let found = -1;
+        for (let i=0; i<=occurrence; i++) { const next=original.indexOf(node.text,found+1); if(next<0) break; found=next; }
+        if (found >= 0 && column - 1 >= found && column - 1 <= found + node.text.length) matched = node;
+      }
+    }
+    ts.forEachChild(node,visit);
+  };
+  visit(file);
+  const checker = analysis.program.getTypeChecker();
+  target = matched ?? target;
+  const completions = checker.getSymbolsInScope(target, ts.SymbolFlags.Value | ts.SymbolFlags.Type | ts.SymbolFlags.Alias)
+    .filter(symbol => symbol.declarations?.some(d => analysis.documents.has(d.getSourceFile().fileName) && !['화면연결'].includes(symbol.name)))
+    .map(symbol => ({ name: symbol.name, detail: checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol,target)) }));
+  if (!matched) return { completions, definitions: [] };
+  let symbol = checker.getSymbolAtLocation(matched);
+  if (!symbol) return { completions, definitions: [] };
+  if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+  const type = checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol,matched),matched,ts.TypeFormatFlags.NoTruncation);
+  const definitions = (symbol.declarations ?? []).flatMap(declaration => {
+    const name = declaration.name ?? declaration;
+    const sourceFile=name.getSourceFile();
+    const doc=analysis.documents.get(sourceFile.fileName);
+    const position=sourceFile.getLineAndCharacterOfPosition(name.getStart(sourceFile));
+    if (!doc || !doc.lineMap[position.line]) return [];
+    const location=mapDiagnostic({file:sourceFile,start:name.getStart(sourceFile),length:name.getWidth(sourceFile),code:0,messageText:'',category:ts.DiagnosticCategory.Message},analysis.documents);
+    return [{filePath:path.resolve(location.filePath),line:location.line,column:location.column,length:location.length}];
+  });
+  return { hover: `${symbol.name}: ${type}`, completions, definitions };
+}

package/dist/emitter.js

@@ -0,0 +1,39 @@
+import ts from 'typescript';
+import path from 'node:path';
+import { analyzeSource } from './checker.js';
+import { HangulScriptError, mapDiagnostic } from './diagnostics.js';
+
+// Keep JavaScript and declaration imports consistent with emitted filenames.
+function rewriteImports(context) {
+  const visit = node => {
+    if (ts.isStringLiteral(node) && node.parent && node.text.endsWith('.hgs') &&
+      ((ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) && node.parent.moduleSpecifier === node ||
+       ts.isCallExpression(node.parent) && node.parent.expression.kind === ts.SyntaxKind.ImportKeyword && node.parent.arguments[0] === node)) {
+      return context.factory.createStringLiteral(node.text.replace(/\.hgs$/, '.js'));
+    }
+    // afterDeclarations nodes do not always carry parent links.
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.endsWith('.hgs')) {
+      return context.factory.updateImportDeclaration(node, node.modifiers, node.importClause, context.factory.createStringLiteral(node.moduleSpecifier.text.replace(/\.hgs$/, '.js')), node.attributes);
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.endsWith('.hgs')) {
+      return context.factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, context.factory.createStringLiteral(node.moduleSpecifier.text.replace(/\.hgs$/, '.js')), node.attributes);
+    }
+    return ts.visitEachChild(node, visit, context);
+  };
+  return node => ts.visitNode(node, visit);
+}
+
+export function emitSource(source, filePath) {
+  const result = analyzeSource(source, filePath);
+  if (result.hasErrors) throw new HangulScriptError(result.diagnostics);
+  const files = new Map();
+  const emitted = result.program.emit(undefined, (name, content) => files.set(name, content), undefined, undefined, { before: [rewriteImports], afterDeclarations: [rewriteImports] });
+  if (emitted.emitSkipped) throw new HangulScriptError(emitted.diagnostics.map(d => mapDiagnostic(d, result.documents)));
+  const modules = [...result.documents].map(([virtual, doc]) => ({
+    sourcePath: doc.filePath,
+    javascript: files.get(virtual.replace(/\.ts$/, '.js')) ?? '',
+    declaration: files.get(virtual.replace(/\.ts$/, '.d.ts')) ?? ''
+  }));
+  const root = modules.find(module => module.sourcePath === path.resolve(filePath));
+  return { javascript: root.javascript, declaration: root.declaration, modules };
+}

package/dist/formatter.d.ts

@@ -0,0 +1,2 @@
+/** Preserve expression/literal contents while normalizing indentation and whitespace. */
+export function formatSource(source: string, options?: { tabSize?: number }): string;

package/dist/formatter.js

@@ -0,0 +1,29 @@
+import { compileSource } from './transformer.js';
+
+/** Normalize indentation and whitespace without rewriting expressions or literals. */
+export function formatSource(source, { tabSize = 4 } = {}) {
+  if (!Number.isInteger(tabSize) || tabSize < 1 || tabSize > 8) throw new RangeError('들여쓰기 폭은 1~8 사이의 정수여야 합니다.');
+  const eol = source.includes('\r\n') ? '\r\n' : '\n';
+  const expanded = source.replace(/^[ \t]*\t[ \t]*/gm, prefix => {
+    let width = 0;
+    for (const c of prefix) width += c === '\t' ? tabSize - width % tabSize : 1;
+    return ' '.repeat(width);
+  });
+  compileSource(expanded); // Refuse to guess the intended structure of invalid code.
+  const levels = [0];
+  const output = [];
+  for (const raw of expanded.split(/\r?\n/)) {
+    const text = raw.trim();
+    if (!text) { if (output.length && output.at(-1) !== '') output.push(''); continue; }
+    const indent = raw.length - raw.trimStart().length;
+    if (text.startsWith('#')) {
+      const depth = levels.filter(level => level < indent).length;
+      output.push(' '.repeat(depth * tabSize) + text); continue;
+    }
+    while (levels.at(-1) > indent) levels.pop();
+    if (indent > levels.at(-1)) levels.push(indent);
+    output.push(' '.repeat((levels.length - 1) * tabSize) + raw.trimStart().trimEnd());
+  }
+  while (output.at(-1) === '') output.pop();
+  return output.length ? output.join(eol) + eol : '';
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export function compileFile(inputPath: string, outputPath: string): Promise<stri
 export function compileFileToDefaultDestination(inputPath: string): Promise<string>;
 export interface LintResult {
   diagnostics: readonly ts.Diagnostic[];
+  sourceDiagnostics: readonly SourceDiagnostic[];
   formattedDiagnostics: string;
   hasErrors: boolean;
 }
@@ -13,3 +14,11 @@ export function lintFile(inputPath: string, compilerOptions?: ts.CompilerOptions
 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 }>;
+
+export interface SourceDiagnostic { filePath: string; line: number; column: number; length: number; code: number | string; message: string; severity: 'error' | 'warning'; }
+export interface CheckSettings { files?: ReadonlyMap<string, string>; allFiles?: boolean; libDirectory?: string; compilerOptions?: ts.CompilerOptions; }
+export function checkSource(source: string, filePath?: string, settings?: CheckSettings): { diagnostics: SourceDiagnostic[]; hasErrors: boolean };
+export function formatSourceDiagnostics(diagnostics: readonly SourceDiagnostic[]): string;
+export class HangulScriptError extends Error { diagnostics: SourceDiagnostic[]; constructor(diagnostics: SourceDiagnostic[]); }
+
+export { formatSource } from './formatter.js';

package/dist/index.js

@@ -1,102 +1,11 @@
 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);
-}
+import { analyzeSource } from './checker.js';
+import { formatSourceDiagnostics } from './diagnostics.js';
+import { emitSource } from './emitter.js';
+export { checkSource } from './checker.js';
+export { HangulScriptError, formatSourceDiagnostics } from './diagnostics.js';
 
 export function compileString(source) {
   return compileSource(source);
@@ -118,16 +27,13 @@ export async function compileFileToDefaultDestination(inputPath) {
 }
 
 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);
+  compileSource(source); // Keep syntax errors explicit for callers of the legacy lint API.
+  const result = analyzeSource(source, filePath, { compilerOptions });
   return {
-    diagnostics,
-    formattedDiagnostics: formatDiagnostics(ts, diagnostics),
-    hasErrors: diagnostics.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
+    diagnostics: result.nativeDiagnostics,
+    sourceDiagnostics: result.diagnostics,
+    formattedDiagnostics: formatSourceDiagnostics(result.diagnostics),
+    hasErrors: result.hasErrors
   };
 }
 
@@ -140,42 +46,30 @@ 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$/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')) ?? ''
-  };
+  const { javascript, declaration } = emitSource(source, filePath);
+  return { javascript, declaration };
 }
 
 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 };
+  const { javascript, declaration, modules } = emitSource(source, inputPath);
+  const rootDirectory = path.dirname(path.resolve(inputPath));
+  const destinations = modules.map(module => {
+    const relative = path.relative(rootDirectory, module.sourcePath);
+    if (relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+      throw new Error('빌드 입력 파일의 폴더 밖에 있는 .hgs 모듈은 지원하지 않습니다. 공통 상위 폴더에 진입 파일을 두세요.');
+    }
+    const base = path.join(outputDirectory, relative.replace(/\.hgs$/, ''));
+    return { ...module, javascriptPath: base + '.js', declarationPath: base + '.d.ts' };
+  });
+  // Validate the complete graph before writing any output.
+  for (const module of destinations) {
+    await mkdir(path.dirname(module.javascriptPath), { recursive: true });
+    await writeFile(module.javascriptPath, module.javascript, 'utf8');
+    await writeFile(module.declarationPath, module.declaration, 'utf8');
+  }
+  const root = destinations.find(module => module.sourcePath === path.resolve(inputPath));
+  return { javascript, declaration, javascriptPath: root.javascriptPath, declarationPath: root.declarationPath };
 }
+
+export { formatSource } from './formatter.js';

package/dist/loader.js

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { analyzeSource } from './checker.js';
+import { HangulScriptError } from './diagnostics.js';
+export async function load(url, context, nextLoad) {
+  if (url.startsWith('file:') && new URL(url).pathname.endsWith('.hgs')) {
+    const filePath=fileURLToPath(url);
+    const source=await readFile(filePath,'utf8');
+    const result=analyzeSource(source,filePath);
+    if(result.hasErrors) throw new HangulScriptError(result.diagnostics);
+    const compiled=ts.transpileModule(result.compiled,{compilerOptions:{module:ts.ModuleKind.ESNext,target:ts.ScriptTarget.ES2022}}).outputText;
+    return {format:'module',source:compiled,shortCircuit:true};
+  }
+  return nextLoad(url,context);
+}

package/dist/register.js

@@ -0,0 +1,2 @@
+import { register } from 'node:module';
+register('./loader.js',import.meta.url);

package/dist/runtime.js

@@ -42,4 +42,3 @@ function 범위(시작: number, 끝?: number, 간격 = 1): number[] {
   return Array.from({ length: 개수 }, (_, 순서) => 시작 + 순서 * 간격);
 }
 `;
-

package/dist/sentences.js

@@ -6,8 +6,12 @@ const identifier = /^[\p{L}_$][\p{L}\p{N}_$]*$/u;
 const functionName = /^[\p{L}_$][\p{L}\p{N}_$]*(?:<.+>)?$/u;
 const obsolete = /^(?:상수|변수|함수|반환|클래스|가져오기|내보내기|반복|비동기함수|스위치|선택|케이스|경우|인터페이스|열거형|시도|잡기|마침내|던지기|선언|추상)(?:\s|[({*])|^콘솔\.출력/u;
 
-export function compileSentences(source, { includeRuntime = true } = {}) {
-  const output = includeRuntime ? [sentenceRuntime] : [];
+export function compileSentences(source, { includeRuntime = true, withMapping = false } = {}) {
+  const output = [];
+  const lineMap = [];
+  let currentLine = 0;
+  const push = code => { output.push(code); lineMap.push(...code.split('\n').map(() => currentLine)); };
+  if (includeRuntime) push(sentenceRuntime);
   const frames = [{ indent: 0, kind: 'root' }];
   let pending = null;
   const lines = source.split(/\r?\n/);
@@ -19,6 +23,7 @@ export function compileSentences(source, { includeRuntime = true } = {}) {
     return false;
   };
   for (let index = 0; index < lines.length; index++) {
+    currentLine = index + 1;
     const raw = lines[index];
     const text = raw.trim();
     if (!text || text.startsWith('#')) continue;
@@ -33,12 +38,12 @@ export function compileSentences(source, { includeRuntime = true } = {}) {
     let closed;
     while (indent < frames.at(-1).indent) {
       closed = frames.pop();
-      output.push(closed.kind === 'case' ? 'break; }' : '}');
+      push(closed.kind === 'case' ? 'break; }' : '}');
     }
     if (indent !== frames.at(-1).indent) fail('이전 블록과 들여쓰기를 맞춰 주세요.');
     const parent = frames.at(-1).kind;
-    const open = (code, kind) => { output.push(code + ' {'); pending = { kind }; };
-    const emit = code => output.push(code);
+    const open = (code, kind) => { push(code + ' {'); pending = { kind }; };
+    const emit = code => push(code);
     const exp = value => expression(value);
     const top = () => { if (parent !== 'root') fail('가져오기·공개·타입 선언은 파일의 최상위에 작성하세요.'); };
     let m;
@@ -132,7 +137,8 @@ export function compileSentences(source, { includeRuntime = true } = {}) {
   while (frames.length > 1) {
     const frame = frames.pop();
     if (frame.kind === 'do') throw new SyntaxError('먼저 실행한다 블록 뒤에 반복 조건이 필요합니다.');
-    output.push(frame.kind === 'case' ? 'break; }' : '}');
+    push(frame.kind === 'case' ? 'break; }' : '}');
   }
-  return output.join('\n');
+  const code = output.join('\n');
+  return withMapping ? { code, lineMap } : code;
 }

package/dist/transformer.d.ts

@@ -1,2 +1,5 @@
 /** Convert keyword-style or sentence-style .hgs source into TypeScript. */
 export function compileSource(source: string): string;
+
+export interface MappedSource { code: string; lineMap: number[]; }
+export function compileMappedSource(source: string): MappedSource;

package/dist/transformer.js

@@ -5,3 +5,9 @@ export function compileSource(source) {
   if (typeof source !== 'string') throw new TypeError('한글스크립트 소스는 문자열이어야 합니다.');
   return compileSentences(source);
 }
+
+/** Generated TypeScript lines map to 1-based HGS lines; runtime lines map to zero. */
+export function compileMappedSource(source) {
+  if (typeof source !== 'string') throw new TypeError('한글스크립트 소스는 문자열이어야 합니다.');
+  return compileSentences(source, { withMapping: true });
+}

package/dist/vite.js

@@ -1,21 +1,28 @@
 import ts from 'typescript';
-import { compileSource } from './transformer.js';
+import { analyzeSource } from './checker.js';
+import { HangulScriptError } from './diagnostics.js';
 
-/** Build-time .hgs imports for Vite projects, including React and Vue. */
+/** Semantic checking is mandatory in both Vite development and production builds. */
 export default function hangulscript() {
+  const files = new Map();
   return {
     name: 'hangulscript',
     enforce: 'pre',
+    buildStart() { files.clear(); },
+    watchChange(id, change) { if (change.event === 'delete') files.delete(id.split('?')[0]); },
     transform(source, id) {
-      if (!/\.hgs$/.test(id.split('?')[0]) || /[?&](?:raw|url)(?:[=&]|$)/.test(id)) return null;
-      const compiled = compileSource(source);
-      const result = ts.transpileModule(compiled, {
-        fileName: id.replace(/\.hgs(?:\?.*)?$/, '.ts'),
-        compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, sourceMap: false },
-        reportDiagnostics: true
-      });
-      const errors = (result.diagnostics ?? []).filter(d => d.category === ts.DiagnosticCategory.Error);
-      if (errors.length) throw new Error(errors.map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n')).join('\n'));
+      const filePath = id.split('?')[0];
+      if (!/\.hgs$/.test(filePath) || /[?&](?:raw|url)(?:[=&]|$)/.test(id)) return null;
+      files.set(filePath, source);
+      const checked = analyzeSource(source, filePath, { files, allFiles: true });
+      if (typeof this?.addWatchFile === 'function') for (const doc of checked.documents.values()) this.addWatchFile(doc.filePath);
+      if (checked.hasErrors) {
+        const error = new HangulScriptError(checked.diagnostics);
+        const first = checked.diagnostics.find(d => d.severity === 'error');
+        if (typeof this?.error === 'function') return this.error({ message: error.message, id: first.filePath, loc: { file: first.filePath, line: first.line, column: first.column - 1 } });
+        throw error;
+      }
+      const result = ts.transpileModule(checked.compiled, { compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext } });
       return { code: result.outputText, map: null };
     }
   };

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uiwwsw/hangulscript",
-  "version": "0.6.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"