saju8z 0.0.0-stage → 1.0.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# saju8z
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+브라우저와 Node.js에서 생년월일시를 사주팔자로 변환하는 오프라인 만세력 계산 라이브러리입니다. 양력·한국 음력·윤달을 지원하며, 사주팔자와 십성 계산 결과를 객체·텍스트·JSON으로 사용할 수 있습니다.
+
+- TypeScript 타입 선언과 ESM·CommonJS 빌드 제공
+- 네트워크·API 키·데이터베이스 없이 실행
+- 현재 시각과 실행 환경의 시간대에 의존하지 않는 계산
+- 음력 변환 의존성을 번들에 포함하여 별도 런타임 의존성 설치 불필요
+
+Node.js에서는 22 이상을 사용합니다. 브라우저에서는 ES2022를 지원하는 환경과 ESM 번들러를 사용할 수 있습니다.
+
+## 설치
+
+사용할 프로젝트에서 npm 패키지를 설치합니다.
+
+```sh
+npm install saju8z
+```
+
+설치 후 `saju8z`에서 함수를 가져와 바로 사용할 수 있습니다. 패키지 사용을 위해 이 저장소를 내려받거나 직접 빌드할 필요는 없습니다.
+
+## 빠른 시작
+
+Node.js ESM, TypeScript, 브라우저 번들러 환경에서 동일하게 사용합니다.
+
+```js
+import { calculateSajuChart, formatSajuChart } from "saju8z";
+
+const result = calculateSajuChart({
+  date: "2000-02-29",
+  time: "00:10",
+  gmt: "+09:00"
+});
+
+console.log(result.fourPillars); // 사주팔자 객체
+console.log(result.tenGods); // 십성 객체
+console.log(formatSajuChart(result, "text")); // Markdown 표 문자열
+console.log(formatSajuChart(result, "json")); // JSON 문자열
+```
+
+CommonJS에서는 `require`로 가져옵니다.
+
+```js
+const { calculateSajuChart, formatSajuChart } = require("saju8z");
+
+const result = calculateSajuChart({
+  date: "2000-02-29",
+  time: "00:10",
+  gmt: "+09:00"
+});
+console.log(formatSajuChart(result));
+```
+
+## 입력
+
+`calculateSajuChart(input)`은 다음 객체를 받습니다.
+
+| 필드        | 타입      | 필수     | 설명                                                   |
+| ----------- | --------- | -------- | ------------------------------------------------------ | ------------------------------------- |
+| `date`      | `string`  | 예       | `YYYY-MM-DD`. 선택한 달력 기준의 날짜                  |
+| `time`      | `string`  | 예       | `HH:mm`, `00:00`\~`23:59`. 초는 지원하지 않음          |
+| `gmt`       | `string`  | 예       | 부호를 포함한 고정 시차 `±HH:mm`, `-12:00`\~`+14:00`   |
+| `calendar`  | `"solar"  | "lunar"` | 아니요                                                 | 양력 또는 한국 음력. 기본값 `"solar"` |
+| `leapMonth` | `boolean` | 아니요   | 음력 윤달 여부. 기본값 `false`, 음력에서만 `true` 허용 |
+
+GMT는 출생 당시 날짜·시간의 시차를 직접 지정합니다. 예를 들어 한국 표준시는 `+09:00`, UTC는 `+00:00`입니다. 실행 환경의 시간대나 지역 이름으로 자동 추정하지 않습니다.
+
+음력 윤달은 다음과 같이 입력합니다.
+
+```js
+const result = calculateSajuChart({
+  date: "2017-05-01",
+  time: "12:00",
+  gmt: "+09:00",
+  calendar: "lunar",
+  leapMonth: true
+});
+// 양력 2017-06-24 12:00, GMT+09:00 입력과 같은 결과
+```
+
+## 결과와 출력 형식
+
+`calculateSajuChart`는 JSON으로 직렬화 가능한 `SajuChartResult` 객체를 반환합니다.
+
+| 필드                  | 내용                                                                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `normalizedDateTime`  | 양력으로 변환하고 GMT+09:00으로 환산한 `{ year, month, day, hour, minute }`                                 |
+| `calculationDateTime` | 환산 시각에 -30분 보정을 적용한 계산 시각                                                                   |
+| `fourPillars`         | `year`, `month`, `day`, `hour`의 사주팔자. 각 값은 `{ stem, branch }`                                       |
+| `tenGods`             | 일간 기준 십성. `yearStem`, `yearBranch`, `monthStem`, `monthBranch`, `dayBranch`, `hourStem`, `hourBranch` |
+| `calculationProfile`  | 계산 규칙 식별자. 현재 `saju8z-fixed-gmt-kst-minus30-v1`                                                    |
+
+천간·지지·십성은 `"병"`, `"진"`, `"식신"`과 같은 한국어 문자열입니다. 일간 자체의 십성 필드는 없으며, 텍스트 표에서는 `본원`으로 표시합니다.
+
+### 텍스트
+
+`formatSajuChart(result)` 또는 `formatSajuChart(result, "text")`는 시주·일주·월주·년주 순서의 Markdown 표를 반환합니다. 천간·지지의 한자, 오행, 십성을 포함합니다. 빠른 시작 예제의 출력은 다음과 같습니다.
+
+```text
+| 구분 | 시주 | 일주 | 월주 | 년주 |
+| --- | --- | --- | --- | --- |
+| 천간 | 무(戊) | 병(丙) | 무(戊) | 경(庚) |
+| 천간 오행 | 土 | 火 | 土 | 金 |
+| 천간 십성 | 식신 | 본원 | 식신 | 편재 |
+| 지지 | 자(子) | 진(辰) | 인(寅) | 진(辰) |
+| 지지 오행 | 水 | 土 | 木 | 土 |
+| 지지 십성 | 정관 | 식신 | 편인 | 식신 |
+```
+
+### JSON
+
+`formatSajuChart(result, "json")`은 결과 객체 전체를 들여쓰기한 JSON 문자열로 반환합니다. 저장하거나 전송할 때 사용합니다. 객체가 필요하면 `calculateSajuChart`의 반환값을 바로 사용하면 됩니다.
+
+```js
+const json = formatSajuChart(result, "json");
+const restored = JSON.parse(json);
+console.log(restored.fourPillars.day); // { stem: "병", branch: "진" }
+```
+
+## TypeScript와 오류 처리
+
+주 진입점은 계산·출력 함수, 오류 클래스와 세 가지 타입을 제공합니다.
+
+```ts
+import { calculateSajuChart, formatSajuChart, UserInputError } from "saju8z";
+import type { SajuChartInput, SajuChartResult, SajuChartFormat } from "saju8z";
+
+const input: SajuChartInput = {
+  date: "2000-02-29",
+  time: "00:10",
+  gmt: "+09:00"
+};
+const format: SajuChartFormat = "json";
+
+try {
+  const result: SajuChartResult = calculateSajuChart(input);
+  console.log(formatSajuChart(result, format));
+} catch (error) {
+  if (error instanceof UserInputError) {
+    console.error(error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+잘못된 날짜·시각·GMT, 지원 범위 밖 날짜, 존재하지 않는 윤달은 `UserInputError`를 발생시킵니다. 출력 형식은 `"text"`와 `"json"`만 허용합니다.
+
+## 추가 진입점
+
+| 가져오기 경로   | 용도                                                                     |
+| --------------- | ------------------------------------------------------------------------ |
+| `saju8z`        | `calculateSajuChart`, `formatSajuChart`, `UserInputError` 및 입출력 타입 |
+| `saju8z/core`   | 저수준 계산 함수, 상수, 간지·오행 데이터와 도메인 타입                   |
+| `saju8z/lunar`  | `lunarToSolar`, `lunarMonthDays`, `hasLunarLeapMonth`                    |
+| `saju8z/format` | `formatSajuChart`, `SajuChartFormat`, `SajuChartResult` 타입             |
+
+일반적인 만세력 계산에는 `saju8z`를 사용합니다. 저수준 함수는 입력 검증과 보정 적용 방식을 호출자가 확인해야 합니다.
+
+## 계산 기준과 지원 범위
+
+1. 음력이면 양력으로 변환합니다.
+2. 입력 GMT에서 GMT+09:00으로 환산합니다.
+3. -30분을 보정한 시각으로 사주팔자를 계산합니다.
+
+년주는 입춘, 월주는 프로젝트의 고정 절입 시각 표, 일주는 자정을 기준으로 합니다. 고정 절입 표는 실제 연도별 천문 절기 시각과 차이가 있을 수 있습니다. 서머타임·역사적 시차·출생지 경도 보정은 자동 적용하지 않습니다.
+
+양력 입력과 GMT+09:00 환산 날짜는 1900~2100년을 지원합니다. 음력은 1900년부터 음력 2050년 11월 18일까지의 유효 날짜를 지원합니다. -30분 보정으로 1900년 첫날이 전년 말로 이동할 수 있습니다.
+
+성별 입력은 필요하지 않습니다. 대운·세운·운세·성격 해석 기능은 제공하지 않습니다.
+
+## 소스 개발과 패키지 검증
+
+라이브러리 자체를 수정하는 경우 저장소를 내려받은 뒤 아래 명령을 사용합니다.
+
+```sh
+npm ci
+npm run build        # ESM·CommonJS 번들과 타입 선언 생성
+npm test             # 빌드 후 계산·출력 테스트
+npm run lint
+npm run typecheck
+npm pack --dry-run   # 배포 파일 목록 확인
+npm run test:package # tarball 설치 후 ESM/CJS·타입·브라우저·시간대 검증
+npm pack             # saju8z-1.0.0.tgz 생성
+```
+
+계산 원본은 `src/`, 테스트는 `test/`, 빌드·패키지 검증 스크립트는 `scripts/`에 있습니다. JavaScript 스크립트는 `package.json`의 `"type": "module"` 설정에 따라 ES 모듈로 실행합니다. `dist/`는 빌드 산출물이며 npm 패키지에는 실행 번들·타입 선언·README·LICENSE·제3자 고지를 포함합니다.
+
+## 라이선스
+
+이 프로젝트는 [MIT 라이선스](LICENSE)로 배포합니다. Copyright (c) 2026 frogred8.
+
+상업적 사용·수정·재배포를 허용하며, 소프트웨어의 복사본이나 주요 부분에 저작권 및 라이선스 고지를 유지해야 합니다. 소프트웨어는 보증 없이 제공됩니다. 정확한 조건은 LICENSE 전문을 참고하세요.
+
+번들에 포함된 `korean-lunar-calendar`의 원 저작권 및 MIT 라이선스 고지는 [THIRD-PARTY-LICENSES.txt](THIRD-PARTY-LICENSES.txt)에 별도로 보존합니다.

package/THIRD-PARTY-LICENSES.txt

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