@uiwwsw/hangulscript 0.6.0 → 0.8.0

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

@@ -1,10 +1,11 @@
+import { collectionsRuntime } from './collections.js';
 import { uiRuntime } from './ui.js';
 export const sentenceRuntime = `${uiRuntime}
 
 function 출력(...값: unknown[]): void { console.log(...값); }
-function 길이(값: string | readonly unknown[]): number { return 값.length; }
+function 길이(값: string | readonly unknown[] | ReadonlySet<unknown> | ReadonlyMap<unknown, unknown>): number { return "size" in Object(값) ? (값 as ReadonlySet<unknown>).size : (값 as string | readonly unknown[]).length; }
 function 추가<T>(목록: T[], 값: T): void { 목록.push(값); }
-function 포함<T>(목록: readonly T[], 값: T): boolean { return 목록.includes(값); }
+function 포함<T>(목록: readonly T[] | ReadonlySet<T>, 값: T): boolean { return 목록 instanceof Set ? 목록.has(값) : (목록 as readonly T[]).includes(값); }
 function 나누기(글: string, 구분: string): string[] { return 글.split(구분); }
 function 잇기(목록: readonly unknown[], 구분 = ""): string { return 목록.join(구분); }
 function 합계(값: readonly number[]): number { return 값.reduce((합, 항목) => 합 + 항목, 0); }
@@ -33,7 +34,17 @@ function 최댓값(목록: readonly number[]): number {
   let 결과 = 목록[0]; for (const 항목 of 목록) if (항목 > 결과) 결과 = 항목;
   return 결과;
 }
-function 정렬(값: readonly number[]): number[] { return [...값].sort((가, 나) => 가 - 나); }
+function 정렬비교(가: number | string, 나: number | string): number {
+  if (typeof 가 !== typeof 나) throw new Error("같은 종류의 숫자 또는 문자열을 정렬하세요.");
+  if (typeof 가 === "number" && typeof 나 === "number") { if (!Number.isFinite(가) || !Number.isFinite(나)) throw new Error("정렬할 숫자는 유한해야 합니다."); return 가 - 나; }
+  return (가 as string).localeCompare(나 as string, "ko", { numeric: true });
+}
+function 정렬<T extends number | string>(값: readonly T[]): T[];
+function 정렬<T>(값: readonly T[], 비교: (가: T, 나: T) => number): T[];
+function 정렬<T>(값: readonly T[], 비교?: (가: T, 나: T) => number): T[] {
+  if (!비교 && 값.some(항목 => !["number", "string"].includes(typeof 항목) || typeof 항목 === "number" && !Number.isFinite(항목))) throw new Error("정렬할 값은 유한한 숫자 또는 문자열이어야 합니다.");
+  return [...값].sort(비교 ?? ((가, 나) => 정렬비교(가 as number | string, 나 as number | string)));
+}
 function 범위(시작: number, 끝?: number, 간격 = 1): number[] {
   if (끝 === undefined) { 끝 = 시작; 시작 = 0; }
   if (!Number.isFinite(시작) || !Number.isFinite(끝) || !Number.isFinite(간격) || 간격 === 0) throw new Error("범위에는 유한한 수와 0이 아닌 간격이 필요합니다.");
@@ -41,5 +52,5 @@ function 범위(시작: number, 끝?: number, 간격 = 1): number[] {
   if (개수 > 100000) throw new Error("범위는 최대 100000개까지 만들 수 있습니다.");
   return Array.from({ length: 개수 }, (_, 순서) => 시작 + 순서 * 간격);
 }
+${collectionsRuntime}
 `;
-

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/ROADMAP.md

@@ -0,0 +1,45 @@
+# 한글스크립트의 큰 그림
+
+한글 문장으로 프로그램의 의도를 분명히 쓰고, JavaScript 생태계에서 실행하는 언어를 만듭니다. 현재의 중심은 **문장형 소스 → 타입 검사 → JavaScript + 타입 선언**입니다. 이 문서는 완료 보고가 아니라 현재 지원 범위와 이후 개발의 기준입니다. 기능 추가만으로 1.0을 선언하지 않습니다.
+
+<div class="architecture" role="group" aria-label="한글스크립트 컴파일과 실행 구조"><div><b>01</b><strong>한글 문장 .hgs</strong><span>이름 · 조건 · 행동 · 결과</span></div><div><b>02</b><strong>문법과 들여쓰기</strong><span>정해진 문장 규칙 해석</span></div><div><b>03</b><strong>타입과 오류 검사</strong><span>TypeScript 검사기 활용</span></div><div><b>04</b><strong>JS + .d.ts</strong><span>실행 모듈과 타입 계약</span></div><div><b>05</b><strong>Node · 웹</strong><span>Vite · React · Vue 연결</span></div><div><b>06</b><strong>VS Code · 문서</strong><span>작성 · 이해 · 수정 지원</span></div></div>
+
+## 지금의 기반
+
+| 계층 | 현재 제공 | 부분 지원·한계 | 다음 개발 |
+| --- | --- | --- | --- |
+| 문법 | 문장형 선언·함수·분기·반복·모듈·예외·비동기·클래스·타입 | 정해진 문장만 해석. 전체 JS/TS 소스 호환 아님 | 전용 AST, 문법 오류 복구, 더 정밀한 토큰 위치 |
+| 타입 | TypeScript strict 기본 검사·제네릭·타입 선언 출력 | any·빈 목록의 검사 제한, 변환 토큰 열은 근사할 수 있음 | 더 나은 기본 추론, 문장별 진단, 명시적인 안전성 규칙 |
+| 표준 기능 | 61개 한글 함수: 목록·집합·사전·복사·정렬·숫자·문자열·검증·화면 | 모든 내장 JS API의 한글 별칭은 아님. 일부 원본 변경 함수 존재 | 객체·문자열·날짜 확장, 표준 모듈 분리, 이름 충돌 완화 |
+| 실행과 빌드 | Node 등록 로더·CLI·ESM·JS + .d.ts·Vite | 진입 폴더 밖 HGS 의존성 빌드와 자산 복사 미지원 | 프로젝트 빌드·증분 컴파일·watch·정밀한 소스맵 |
+| 편집기 | 포맷·진단·타입 정보·정의 이동·스코프 자동 완성·스니펫·ㅎ 아이콘 | 전체 속성 완성·자동 import·참조 찾기·이름 변경·디버거 미지원 | LSP로 기능 분리, 증분 분석, 안전한 리팩터링 |
+| 신뢰성 | 문법·실행·타입·문서 예제·프레임워크·실제 편집기 테스트 | 테스트 통과는 모든 입력의 올바름을 뜻하지 않음 | 명세 기반 적합성 테스트·퍼징·회귀·실측 성능 기준 |
+| 문서와 배포 | 버전별 변경 내역·함수 계약·예제·npm·Marketplace·CI | 0.x에서 문법과 API가 바뀔 수 있음 | 마이그레이션 도구·릴리스 규칙·1.0 호환성 약속 |
+
+## 순서대로 만들기
+
+### 1. 지금 있는 언어를 믿고 사용할 수 있게
+
+함수마다 입력·반환·원본 변경·실패 조건을 일관되게 문서화하고 예제를 실행해 검사합니다. 잘못된 입력과 오류 위치를 회귀 테스트로 남깁니다. 문장형의 모든 조합을 지원한다고 가정하지 않고 지원·부분 지원·미구현을 공개합니다. 현재 0.8 작업은 문서·자료구조·아이콘·배포에 집중합니다.
+
+### 2. 언어 내부를 확장하기 좋은 구조로
+
+현재 문장·들여쓰기는 규칙 기반 파서로 처리하고 표현식에는 TypeScript AST를 활용합니다. 문장 전체를 나타내는 전용 AST와 범위 정보를 도입한 뒤 문법 검사·타입 연결·출력·포맷을 분리합니다. 이를 기반으로 오류를 여러 개 복구해서 보여주고, 정확한 소스맵과 프로젝트 단위 증분 분석을 만듭니다.
+
+### 3. 실용적인 개발 환경을 완성하기
+
+편집기의 전체 속성 자동 완성·자동 import·참조와 이름 변경을 LSP에 연결합니다. 프로젝트 설정·증분 빌드·테스트 명령을 제공하고 React/Vue에서 안정적으로 쓰는 예제를 유지합니다. 파일·네트워크·날짜·객체 등은 Node와 브라우저의 권한 차이를 구분한 선택 모듈로 설계합니다.
+
+### 4. 문장이 탄탄할수록 검사할 수 있는 내용 늘리기
+
+이름과 타입은 등장인물과 사물을, 사전·사후 조건은 세계의 규칙을, 함수와 모듈은 사건과 장면을 표현합니다. 현재는 `확인한다`로 실행 중 조건을 검사할 수 있습니다. 다음으로 입력 조건·결과 조건·예제 테스트를 더 읽기 쉬운 문장으로 선언하는 방식을 설계할 수 있습니다. 효과가 있는 문법인지 작은 실험과 실제 예제로 먼저 검증합니다.
+
+### 5. 1.0을 위한 기준 정하기
+
+문법 명세와 표준 API를 고정하고 호환성·폐기 정책을 확정합니다. 핵심 오류 사례, 적합성 테스트, 편집기 기능, 선언 출력, Node·브라우저·프레임워크 연동을 릴리스 기준으로 정합니다. 성능은 환경과 입력 크기를 함께 공개하고 회귀를 추적합니다. 완료되지 않은 항목이 있으면 이름을 붙여 공개합니다.
+
+## AI와 별도 실행 엔진의 위치
+
+핵심 문법·타입·컴파일·조건 검사에는 AI API가 필요하지 않습니다. 자유로운 산문에서 의도를 추출하는 기능은 선택적인 작성 보조로 실험할 수 있고 로컬 모델도 가능합니다. 생성한 결과도 같은 검사·테스트를 통과해야 합니다. 현재 자유 산문 실행, AI 기반 문장 해석, 자동 정형 증명은 제공하지 않습니다.
+
+JS + .d.ts 경로는 기존 생태계와 타입을 재사용하는 현재의 실행 계약입니다. 독립 VM·바이트코드·네이티브 출력은 별도의 큰 프로젝트이므로 실제 요구와 측정 결과가 생기면 검토합니다. 정식 문서와 지원 도구를 갖추는 데 독립 실행 엔진이 필수인 것은 아닙니다.

package/docs/frameworks.md

@@ -0,0 +1,152 @@
+# React·Vue에서 한글스크립트 사용하기
+
+이 가이드는 `@uiwwsw/hangulscript@0.8.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.8.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/guides/collections.md

@@ -0,0 +1,61 @@
+# 목록·집합·사전 고르기
+
+배열은 순서를 가진 **목록**, Set은 중복 없는 **집합**, Map은 키와 값을 연결하는 **사전**으로 표현합니다. 값과 목적에 맞춰 자료구조를 고르면 코드의 뜻이 더 명확해집니다.
+
+```hgs
+점수들은 [75, 92, 88, 92]이다
+통과점수는 골라내기(점수들, 점수 => 점수 >= 80)이다
+서로다른점수는 집합(통과점수)이다
+출력(내림차순(목록으로(서로다른점수)))
+```
+
+`배열`을 나타내는 타입은 `목록<숫자>` 또는 `숫자[]`입니다. 집합은 `집합<문자열>`, 사전은 `사전<문자열, 숫자>`로 적습니다. 함수의 매개변수에 타입을 쓰면 잘못된 값이 들어오는 호출을 빌드 단계에서 찾을 수 있습니다.
+
+```hgs
+재고: 사전<문자열, 숫자>는 사전()이다
+사전에담기(재고, "사과", 3)
+사전에담기(재고, "배", 5)
+출력(키목록(재고), 사전에서읽기(재고, "사과"))
+```
+
+## 원본과 복사본
+
+`정렬`, `오름차순`, `내림차순`, `골라내기`, `각각바꾸기`, `뒤집기`, `잘라내기`는 원본 배열을 바꾸지 않습니다. `추가`, `집합에추가`, `집합에서삭제`, `사전에담기`, `사전에서삭제`는 원본을 바꿉니다. 함수별 참조 문서에서 확인하세요.
+
+얕은 복사는 바깥 그릇만 새로 만듭니다. 안쪽 객체는 공유합니다. 깊은 복사는 복제 가능한 안쪽 값까지 별도로 만듭니다.
+
+```hgs
+원본은 [{ 점수: 10 }]이다
+얕은복사본은 얕게복사(원본)이다
+깊은복사본은 깊게복사(원본)이다
+얕은복사본[0].점수 = 20
+출력(원본[0].점수, 깊은복사본[0].점수)
+```
+
+결과는 `20 10`입니다. 깊은 복사는 함수·DOM 노드 등 복제 불가능한 값에 오류를 냅니다. 객체를 중복 제거하거나 집합에 넣을 때에는 내용이 같아도 참조가 다르면 서로 다른 값입니다.
+
+## 정렬 기준 쓰기
+
+```hgs
+학생들은 [{ 이름: "하늘", 점수: 88 }, { 이름: "바다", 점수: 92 }]이다
+점수순은 기준정렬(학생들, 학생 => 학생.점수, "내림차순")이다
+출력(점수순)
+```
+
+숫자는 크기로, 문자열은 한국어 locale의 자연 정렬로 비교합니다. 같은 키의 항목은 원래 순서를 유지합니다. 더 복잡한 순서는 `정렬(목록, 비교함수)`로 표현하며 비교 함수는 음수·0·양수를 반환해야 합니다.
+
+## 비용을 알고 쓰기
+
+목록 변환·필터·복사는 항목 수에 비례한 시간과 새 배열 메모리가 필요합니다. 정렬은 일반적으로 O(n log n), 집합·사전 검색은 평균적으로 상수 시간에 가깝습니다. 깊은 복사는 중첩 데이터 전체의 시간·메모리를 사용합니다. `기준정렬`은 기준 함수를 항목마다 한 번만 호출합니다. 큰 반복에서 불필요하게 복사하지 말고, 2초 제한의 웹 데모와 일반 Node 실행을 구분하세요.
+
+## 문장처럼 적기
+
+정렬·복사·중복 제거는 값 자리에서 다음 문장으로도 적을 수 있습니다. 함수 호출과 같은 결과이며, 정해진 표현만 지원합니다.
+
+```hgs
+점수들은 [88, 92, 88]이다
+점수순은 점수들을 내림차순으로 정렬한 값이다
+서로다른값은 점수들에서 중복을 제거한 값이다
+독립본은 점수들을 깊게 복사한 값이다
+출력(점수순, 서로다른값, 독립본)
+```