npm package: @kwangsugkim/ksgen
Description: Language-agnostic source code generator
Latest version: 1.0.4

# ksgen

🌐 **홈페이지**: [https://lang.ksgenai.com/](https://lang.ksgenai.com/)

**ksgen**은 소스 코드를 분석해서 **Token + AST(JSON)** 를 만들고, 이를 **Template(JavaScript)** 로 가공해 문서/리포트/시각화 결과를 자동 생성하는 도구입니다.

쉽게 말하면,
- 코드를 기계가 이해할 수 있는 구조로 바꾼 뒤
- 사람이 바로 활용할 수 있는 결과물로 출력해주는
**코드 분석 자동화 엔진**입니다.

---

## 👀 사용자 관점에서 ksgen이 좋은 이유

- 반복 작업(함수 목록 정리, 호출 관계 작성, API 사용 목록 수집)을 자동화할 수 있습니다.
- 언어가 달라도 결과 구조를 비슷하게 맞춰, 팀 문서화 표준을 만들기 쉽습니다.
- 템플릿만 바꾸면 같은 소스에서 다양한 산출물(보고서, 마크다운, 가이드)을 만들 수 있습니다.
- 신규 인력 온보딩 시 코드 구조를 빠르게 이해시키는 데 도움이 됩니다.

---

## 🎯 활용도 중심 정리

### 1) 개발팀
- 함수/호출 관계 문서 자동 생성
- 공통 규칙(예: 금지 API, 특정 패턴) 추출 리포트 생성
- 코드 리뷰 전 사전 구조 분석

### 2) 아키텍트/리드
- 시스템별 호출 흐름 시각화
- 언어별 문법/구조 차이 비교
- 레거시 코드 파악 속도 향상

### 3) 운영/품질/문서 담당
- 변경 이력용 기술 문서 자동화
- 정기 점검 리포트 템플릿화
- 프로젝트 README/가이드 생성 자동화

---

## 🚀 빠른 시작 (처음 사용자용)

### 설치

```bash
npm i -g @kwangsugkim/ksgen
```

### 도움말 확인

```bash
ksgen --help
```

### npm 프로젝트에 로컬 설치

```bash
npm install --save-dev @kwangsugkim/ksgen
```

로컬 설치 후에는 `npx ksgen` 또는 `package.json`의 script로 실행하는 방식을 권장합니다.

### 가장 빠른 실행 예시 (`-g`)

```bash
ksgen -g c examples/c/input/sample.c examples/c/templates/3.function-call-graph.js result.md
```

실행 결과:
- 입력 소스를 파싱(Token/AST 생성)
- 템플릿을 즉시 실행
- `result.md` 결과 파일 생성

---

## 🧭 추천 사용 흐름

### A. 결과를 빨리 보고 싶을 때
`-g` 한 번으로 끝내기

```bash
ksgen -g <language> <input> <template> <output> [-o <logfile>]
```

### B. 분석 결과를 먼저 검증하고 싶을 때
`-p`로 JSON 생성 → `-t`로 템플릿 실행

```bash
ksgen -p <language> <input> <output.json>
ksgen -t <output.json> <template> <outputfile> [-o <logfile>]
```

---

## 📦 npm 프로젝트에서 ksgen 사용

Node.js `18+` 환경에서 로컬 의존성으로 설치한 뒤, 프로젝트 스크립트에 ksgen 실행 명령을 등록해서 사용하는 방식이 가장 단순합니다.

### 1) 설치

```bash
npm install --save-dev @kwangsugkim/ksgen
```

### 2) 권장 디렉터리 예시

```text
your-project/
 ├─ package.json
 ├─ src/
 ├─ ksgen/
 │   ├─ input/
 │   ├─ json/
 │   ├─ templates/
 │   └─ output/
```

### 3) `package.json` 스크립트 예시

```json
{
    "scripts": {
        "ksgen:parse": "ksgen -p javascript src/index.js ksgen/json/index.json",
        "ksgen:template": "ksgen -t ksgen/json/index.json ksgen/templates/report.js ksgen/output/report.md",
        "ksgen:generate": "ksgen -g javascript src/index.js ksgen/templates/report.js ksgen/output/report.md"
    },
    "devDependencies": {
        "@kwangsugkim/ksgen": "^1.0.3"
    }
}
```

### 4) 실행 예시

```bash
npm run ksgen:parse
npm run ksgen:template
```

또는 한 번에 실행합니다.

```bash
npm run ksgen:generate
```

### 4-1) import 함수로 사용하는 방법

ksgen 모듈은 CLI 외에도 import 가능한 함수 3개를 제공합니다.

- `parseSource`: `-p` 옵션에 대응
- `renderTemplate`: `-t` 옵션에 대응
- `generateFromSource`: `-g` 옵션에 대응

입력은 문자열 또는 JSON 객체를 사용하고, 결과는 문자열 또는 JSON 객체로 반환됩니다.

```ts
import {
    parseSource,
    renderTemplate,
    generateFromSource,
    Token,
    VariableNode,
} from "@kwangsugkim/ksgen";

const parsed = parseSource({
    language: "javascript",
    sourceCode: "function sum(a, b) { return a + b; }",
    sourceFile: "src/sum.js",
});

const tokens: Token[] = parsed.tokens;
const nodes: VariableNode[] = parsed.nodes;

const templated = renderTemplate({
    sourceJson: parsed,
    templateCode: `
module.exports = function () {
        writeln("# Function Report");
        writeln(JSON.stringify(GLOBAL.source.nodes, null, 2));
};
`,
    templateFile: "inline-template.js",
});

const generated = generateFromSource({
    language: "javascript",
    sourceCode: "function sum(a, b) { return a + b; }",
    templateCode: `
module.exports = function () {
        writeln("Source file: " + GLOBAL.source.sourceFile);
};
`,
    sourceFile: "src/sum.js",
    templateFile: "inline-template.js",
});

console.log(parsed.nodes);
console.log(templated.output);
console.log(generated.json);
console.log(generated.output);
```

추가로 바로 실행해볼 수 있는 예제 파일은 다음 경로에 포함되어 있습니다.

- `examples/javascript/templates/import-renderTemplate-sample.js`
- `examples/javascript/import-renderTemplate-sample.js`

함수별 입출력 요약:

| 함수 | 입력 | 출력 |
|---|---|---|
| `parseSource` | `language`, `sourceCode`, `sourceFile?` | 파싱 결과 JSON |
| `renderTemplate` | `sourceJson`, `templateCode`, `templateFile?` | `{ output, log }` |
| `generateFromSource` | `language`, `sourceCode`, `templateCode`, `sourceFile?`, `templateFile?` | `{ json, output, log }` |

공개 타입:

| 타입 | 설명 |
|---|---|
| `Token` | 파싱 결과 토큰 타입 |
| `TokenType` | 토큰 종류 union 타입 |
| `VariableNode` | AST 노드 타입 |
| `ScopeType` | 노드 scope 타입 |
| `KsgenParsedSource` | `parseSource` 반환 타입 |
| `KsgenTemplateResult` | `renderTemplate` 반환 타입 |
| `KsgenGenerateResult` | `generateFromSource` 반환 타입 |

### 5) CI 또는 빌드 파이프라인에 연결

문서/리포트 산출물이 빌드 산출물에 포함되어야 한다면 기존 빌드 스크립트 앞이나 뒤에 연결하면 됩니다.

```json
{
    "scripts": {
        "build": "npm run ksgen:generate && tsc"
    }
}
```

### 6) 사용할 때 주의할 점

- 템플릿 파일은 JavaScript 파일이어야 합니다.
- 로컬 설치 환경에서는 `npx ksgen ...` 또는 npm script를 사용하면 됩니다.
- 언어 이름은 CLI 기준으로 `c`, `cpp`, `java`, `javascript`, `python`, `cobol`, `html`, `jsp`, `sql`, `human` 등을 사용합니다.
- `-t`는 이미 생성된 JSON을 재사용할 때 적합하고, `-g`는 빠르게 결과물을 만들 때 적합합니다.

---

## ☕ Maven 프로젝트에서 ksgen 사용

Maven 프로젝트에서도 ksgen은 Java 라이브러리로 붙는 방식이 아니라, Node.js 기반 CLI 도구를 빌드 과정에서 호출하는 방식으로 사용하는 것이 적절합니다.

권장 방식은 다음과 같습니다.

- `frontend-maven-plugin`으로 Node/npm 환경을 고정
- `npm install`로 ksgen 설치
- Maven lifecycle에서 `npx ksgen` 실행

### 1) 프로젝트 구조 예시

```text
your-maven-project/
 ├─ pom.xml
 ├─ src/main/java/
 ├─ ksgen/
 │   ├─ json/
 │   ├─ templates/
 │   └─ output/
 └─ package.json
```

### 2) 루트 `package.json` 예시

Maven 프로젝트 안에서도 ksgen 실행만을 위한 최소 npm 설정 파일을 두면 관리가 쉬워집니다.

```json
{
    "private": true,
    "devDependencies": {
        "@kwangsugkim/ksgen": "^1.0.3"
    },
    "scripts": {
        "ksgen:java": "ksgen -g java src/main/java/com/example/Sample.java ksgen/templates/java-report.js ksgen/output/java-report.md"
    }
}
```

### 3) `pom.xml` 예시

아래 예시는 `generate-resources` 단계에서 ksgen을 실행하는 구성입니다.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>com.github.eirslett</groupId>
            <artifactId>frontend-maven-plugin</artifactId>
            <version>1.15.0</version>
            <executions>
                <execution>
                    <id>install-node-and-npm</id>
                    <goals>
                        <goal>install-node-and-npm</goal>
                    </goals>
                    <configuration>
                        <nodeVersion>v20.11.1</nodeVersion>
                    </configuration>
                </execution>

                <execution>
                    <id>npm-install</id>
                    <goals>
                        <goal>npm</goal>
                    </goals>
                    <configuration>
                        <arguments>install</arguments>
                    </configuration>
                </execution>

                <execution>
                    <id>run-ksgen</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>npx</goal>
                    </goals>
                    <configuration>
                        <arguments>ksgen -g java src/main/java/com/example/Sample.java ksgen/templates/java-report.js ksgen/output/java-report.md</arguments>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

### 4) Maven에서 JSON 생성과 템플릿 실행을 분리하는 예시

파싱 결과를 별도로 보관하고 싶다면 `-p`와 `-t`를 각각 실행하면 됩니다.

```xml
<execution>
    <id>ksgen-parse</id>
    <phase>generate-resources</phase>
    <goals>
        <goal>npx</goal>
    </goals>
    <configuration>
        <arguments>ksgen -p java src/main/java/com/example/Sample.java ksgen/json/sample.json</arguments>
    </configuration>
</execution>

<execution>
    <id>ksgen-template</id>
    <phase>generate-resources</phase>
    <goals>
        <goal>npx</goal>
    </goals>
    <configuration>
        <arguments>ksgen -t ksgen/json/sample.json ksgen/templates/java-report.js ksgen/output/java-report.md</arguments>
    </configuration>
</execution>
```

### 5) 어떤 경우에 Maven 연동이 유용한가

- Java 소스 구조 문서를 빌드 시점에 자동 생성할 때
- 정적 분석 보조 리포트를 CI 산출물로 남길 때
- 레거시 Java 프로젝트의 함수/구조 파악 문서를 반복 생성할 때

### 6) Maven 연동 시 주의할 점

- ksgen은 Java dependency가 아니라 Node.js CLI 도구입니다.
- 따라서 `pom.xml`에 Maven dependency로 추가하는 방식은 적합하지 않습니다.
- 사내 빌드 환경에서 외부 네트워크가 제한되어 있다면 npm registry 접근 정책을 먼저 확인해야 합니다.
- 멀티 모듈 프로젝트에서는 실행 기준 경로를 루트로 통일하거나 모듈별 템플릿 경로를 분리하는 것이 좋습니다.

---

## 🖥 CLI 옵션 상세

| 옵션 | 설명 | 추천 상황 |
|---|---|---|
| `-p` | Source Code를 파싱해 Token + AST JSON 생성 | 파싱 결과를 먼저 확인/디버깅할 때 |
| `-t` | JSON + Template 실행 | 기존 JSON을 재활용해 여러 템플릿을 돌릴 때 |
| `-g` | 파싱 + 템플릿 실행을 한 번에 수행 | 빠르게 최종 산출물을 만들 때 |

### `-p` 예시

```bash
ksgen -p c examples/c/input/sample.c examples/c/json/c.json
```

### `-t` 예시

```bash
ksgen -t examples/c/json/c.json examples/c/templates/3.function-call-graph.js result.md -o result.log
```

### `-g` 예시

```bash
ksgen -g c examples/c/input/sample.c examples/c/templates/3.function-call-graph.js result.md -o result.log
```

---

## 🧠 핵심 개념 (쉽게 이해하기)

### Token
소스를 문법 단위(키워드, 식별자, 연산자 등)로 쪼갠 데이터입니다.

### AST
Token을 의미 구조(함수, 변수, 호출 관계 등)로 재구성한 트리입니다.

### Template
Token/AST를 입력으로 받아 원하는 출력(문서, 리포트, 코드)을 만드는 JavaScript 함수입니다.

---

## 🧩 템플릿 작성 기본

```js
module.exports = function () {
    writeln("Hello ksgen");
};
```

### 사용 가능한 전역 객체

```text
GLOBAL.source.language     // 언어
GLOBAL.source.sourceFile   // 소스 파일명
GLOBAL.source.tokens       // Token 배열
GLOBAL.source.variables    // AST Node 배열
```

### 출력 API

```text
write(text)            // 현재 줄에 출력
writeln(text)          // 줄바꿈 출력
insertln(index,text)   // 특정 라인 삽입
updateln(index,text)   // 특정 라인 수정
deleteln(index)        // 특정 라인 삭제
```

---

## 🌐 Web Demo

Web Demo는 ksgen 동작을 UI로 확인할 수 있는 학습/검증용 환경입니다.

추천 사용 순서:
1. Language 선택
2. Source File 선택
3. Template 선택
4. Run 실행
5. Result / Log 확인

---

## 📦 지원 언어

- C / C++
- Java
- Python
- JavaScript
- COBOL
- HTML / JSP
- PostgreSQL
- MySQL
- MSSQL
- Oracle
- Human (자연어 텍스트)

---

## 🏁 마무리

ksgen은 단순히 코드를 파싱하는 도구가 아니라,
**코드를 이해 가능한 산출물로 바꾸는 자동화 도구**입니다.

특히 다음 목표가 있을 때 효과가 큽니다.
- 코드 문서화 자동화
- 구조 분석 표준화
- 반복 분석 업무 절감

---

## 📄 License

이 프로젝트는 MIT License를 따릅니다.
자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.