ksgen

🌐 홈페이지: https://lang.ksgenai.com/

ksgen은 소스 코드를 분석해서 Token + AST(JSON) 를 만들고, 이를 Template(JavaScript) 로 가공해 문서, 리포트, 변환 결과를 자동 생성하는 CLI 기반 분석 자동화 도구입니다.

개발자용 문서화와 마이그레이션 작업은 물론, AI/AI Agent가 바로 활용할 수 있는 구조화된 출력물까지 생성할 수 있도록 설계되었습니다.

쉽게 말하면,

• 코드를 기계가 이해할 수 있는 구조로 바꾼 뒤
• 사람이 바로 활용할 수 있는 결과물로 출력해주는 코드 분석 자동화 엔진입니다.

👀 사용자 관점에서 ksgen이 좋은 이유

• 반복 작업(함수 목록 정리, 호출 관계 작성, API 사용 목록 수집)을 자동화할 수 있습니다.
• 언어가 달라도 결과 구조를 비슷하게 맞춰, 팀 문서화 표준을 만들기 쉽습니다.
• 템플릿만 바꾸면 같은 소스에서 다양한 산출물(보고서, 마크다운, 가이드)을 만들 수 있습니다.
• 신규 인력 온보딩 시 코드 구조를 빠르게 이해시키는 데 도움이 됩니다.

🎯 활용도 중심 정리

1) 개발팀

• 함수/호출 관계 문서 자동 생성
• 공통 규칙(예: 금지 API, 특정 패턴) 추출 리포트 생성
• 코드 리뷰 전 사전 구조 분석

2) 아키텍트/리드

• 시스템별 호출 흐름 시각화
• 언어별 문법/구조 차이 비교
• 레거시 코드 파악 속도 향상

3) 운영/품질/문서 담당

• 변경 이력용 기술 문서 자동화
• 정기 점검 리포트 템플릿화
• 프로젝트 README/가이드 생성 자동화

🆕 Oracle to PostgreSQL 업데이트

Oracle 마이그레이션 기능이 다음 내용으로 강화되었습니다.

• 신규 Oracle 고급 샘플 추가:
  • examples/sql/input/oracle-advanced-functions.oracle
  • 포함 항목: ROWNUM, CONNECT BY, START WITH, LEVEL, PRIOR, DUAL, SYSDATE, NVL, DECODE, MERGE
• Oracle 템플릿 확장:
  • examples/sql/templates/oracle_to_postgres.oracle.js
  • NVL -> COALESCE, DECODE -> CASE WHEN, SYSDATE -> CURRENT_TIMESTAMP, DUAL -> (VALUES(1)) AS dual 처리 보강
• Oracle 전용 웹 화면 추가:
  • /oracle-migration.html
  • GNB(Global Navigation)에 Oracle Migration 링크 추가

Oracle 고급 샘플 CLI 실행

node dist/bin/ksgen.js -g sql examples/sql/input/oracle-advanced-functions.oracle examples/sql/templates/oracle_to_postgres.oracle.js logs/verify-oracle-to-postgres.md

생성 결과 파일:

• logs/verify-oracle-to-postgres.md

🚀 빠른 시작 (처음 사용자용)

설치

npm i -g @kwangsugkim/ksgen

도움말 확인

ksgen --help

npm 프로젝트에 로컬 설치

npm install --save-dev @kwangsugkim/ksgen

로컬 설치 후에는 npx ksgen 또는 package.json의 script로 실행하는 방식을 권장합니다.

가장 빠른 실행 예시 (-g)

ksgen -g c examples/c/input/sample.c examples/c/templates/3.function-call-graph.js result.md

실행 결과:

• 입력 소스를 파싱(Token/AST 생성)
• 템플릿을 즉시 실행
• result.md 결과 파일 생성

🧭 추천 사용 흐름

A. 결과를 빨리 보고 싶을 때

-g 한 번으로 끝내기

ksgen -g <language> <input> <template> <output> [--binary [encoding]] [-o <logfile>]

<language>에는 auto를 사용할 수 있으며, 이 경우 <input> 파일 확장자로 언어를 자동 판별합니다.

A-2. 폴더 전체를 한 번에 점검하고 싶을 때

직접 하위 파일만 보면 -d, 하위 폴더까지 모두 보면 -D

ksgen -d <language> <input-dir> <template> <output> [-o <logfile>]
ksgen -D <language> <input-dir> <template> <output> [-o <logfile>]

<language>에 auto를 주면, 각 입력 파일의 확장자를 기준으로 파일별 언어를 자동 판별합니다.

-D auto 샘플 (다양한 언어가 섞인 폴더 재귀 처리):

ksgen -D auto examples examples/common/templates/directory-file-metrics-report.js logs/demo-cli-d-auto-file-metrics.md

B. 분석 결과를 먼저 검증하고 싶을 때

-p로 JSON 생성 → -t로 템플릿 실행

ksgen -p <language> <input> <output.json>
ksgen -t <output.json> <template> <outputfile> [--binary [encoding]] [-o <logfile>]

바이너리 결과 파일 생성:

ksgen -t input.json template.js output.png --binary base64
ksgen -g auto input.txt template.js output.wav --binary

• --binary는 템플릿 출력 문자열을 바이너리로 저장합니다.
• 인코딩은 base64(기본값), hex, utf8, latin1을 지원합니다.
• -d, -D는 여러 파일 결과를 한 파일로 합치므로 --binary를 지원하지 않습니다.

-p에서도 <language>를 auto로 주면 <input> 확장자로 언어를 자동 판별합니다.

📦 npm 프로젝트에서 ksgen 사용

Node.js 18+ 환경에서 로컬 의존성으로 설치한 뒤, 프로젝트 스크립트에 ksgen 실행 명령을 등록해서 사용하는 방식이 가장 단순합니다.

1) 설치

npm install --save-dev @kwangsugkim/ksgen

2) 권장 디렉터리 예시

your-project/
 ├─ package.json
 ├─ src/
 ├─ ksgen/
 │   ├─ input/
 │   ├─ json/
 │   ├─ templates/
 │   └─ output/

3) package.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) 실행 예시

npm run ksgen:parse
npm run ksgen:template

또는 한 번에 실행합니다.

npm run ksgen:generate

4-1) import 함수로 사용하는 방법

ksgen 모듈은 CLI 외에도 import 가능한 함수 3개를 제공합니다.

• parseSource: -p 옵션에 대응
• renderTemplate: -t 옵션에 대응
• generateFromSource: -g 옵션에 대응

입력은 문자열 또는 JSON 객체를 사용하고, 결과는 문자열 또는 JSON 객체로 반환됩니다.

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

현재 examples 하위 샘플/템플릿 파일명은 영문 기준으로 정리되어 있으며, 대표 예시는 아래와 같습니다.

• examples/java/templates/variable-function-list.js
• examples/java/templates/class-function-call-analysis.js
• examples/python/templates/function-list-call-info.js
• examples/sql/templates/table-field-list.postgresql.js
• examples/html/templates/link-image-extract.js
• examples/human/templates/pii-detection.js
• examples/human/templates/banned-words-detection.js
• examples/human/templates/translation-report.js
• examples/human/templates/typo-detection-fix.js

함수별 입출력 요약:

| 함수 | 입력 | 출력 | |---|---|---| | parseSource | language, sourceCode, sourceFile? | 파싱 결과 JSON | | renderTemplate | sourceJson, templateCode, templateFile? | { output, log, binaryOutput? } | | generateFromSource | language, sourceCode, templateCode, sourceFile?, templateFile? | { json, output, log, binaryOutput? } |

공개 타입:

| 타입 | 설명 | |---|---| | Token | 파싱 결과 토큰 타입 | | TokenType | 토큰 종류 union 타입 | | VariableNode | AST 노드 타입 | | ScopeType | 노드 scope 타입 | | KsgenParsedSource | parseSource 반환 타입 | | KsgenTemplateResult | renderTemplate 반환 타입 | | KsgenGenerateResult | generateFromSource 반환 타입 |

5) CI 또는 빌드 파이프라인에 연결

문서/리포트 산출물이 빌드 산출물에 포함되어야 한다면 기존 빌드 스크립트 앞이나 뒤에 연결하면 됩니다.

{
    "scripts": {
        "build": "npm run ksgen:generate && tsc"
    }
}

6) 사용할 때 주의할 점

• 템플릿 파일은 JavaScript 파일이어야 합니다.
• 로컬 설치 환경에서는 npx ksgen ... 또는 npm script를 사용하면 됩니다.
• 언어 이름은 CLI 기준으로 auto, c, cpp, java, javascript, typescript, python, cobol, html, xml, jsp, document, sql, json, yml, css, 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) 프로젝트 구조 예시

your-maven-project/
 ├─ pom.xml
 ├─ src/main/java/
 ├─ ksgen/
 │   ├─ json/
 │   ├─ templates/
 │   └─ output/
 └─ package.json

2) 루트 package.json 예시

Maven 프로젝트 안에서도 ksgen 실행만을 위한 최소 npm 설정 파일을 두면 관리가 쉬워집니다.

{
    "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을 실행하는 구성입니다.

<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를 각각 실행하면 됩니다.

<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 | 파싱 + 템플릿 실행을 한 번에 수행 | 빠르게 최종 산출물을 만들 때 | | -d | 폴더 바로 아래 파일들에 대해 -g를 반복 실행 후 결과를 한 파일로 누적 | 특정 디렉터리 단위 점검, 배치 리포트 | | -D | 하위 폴더까지 재귀적으로 -g를 반복 실행 후 결과를 한 파일로 누적 | 프로젝트 전체 분석, 보안/품질 점검 |

-p 예시

ksgen -p c examples/c/input/sample.c examples/c/json/c.json

-t 예시

ksgen -t examples/c/json/c.json examples/c/templates/3.function-call-graph.js result.md -o result.log

-g 예시

ksgen -g c examples/c/input/sample.c examples/c/templates/3.function-call-graph.js result.md -o result.log

--binary 예시

ksgen -t examples/c/json/c.json examples/common/templates/my-image-template.js result.png --binary base64

템플릿에서 사용할 수 있는 바이너리 출력 helper:

• setBinary(data, encoding?): Buffer, Uint8Array, number[], string(인코딩 지정) 지원
• setBinaryBase64(base64)
• setBinaryHex(hex)
• setBinaryFile(relativePath)

-d 예시

ksgen -d json examples/json/input examples/json/templates/json-key-report.js logs/json-batch-report.md

-D 예시

ksgen -D java src examples/java/templates/beginner-function-summary.js logs/java-project-report.md -o logs/java-project-report.log

🔵 바이너리 출력 샘플

소스 코드 분석 결과를 텍스트가 아닌 **바이너리 파일(WAV, BMP, SVG 등)**로 생성할 수 있습니다. 템플릿에서 setBinary() 계열 함수를 호출하면 CLI가 해당 Buffer를 그대로 파일에 저장합니다.

| 템플릿 | 출력 형식 | 설명 | |---|---|---| | binary-tts-silence-wav.js | .wav | 텍스트 길이 기반 PCM WAV (TTS 연결용) | | binary-image-1x1-png.js | .bmp | 토큰 타입별 색상 핑거프린트 BMP 이미지 | | binary-document-pdf.js | .svg | 함수/토큰 구조 SVG 다이어그램 |

템플릿 내 바이너리 출력 헬퍼

setBinary(buffer)                  // Buffer / Uint8Array / number[] / string(인코딩 지정)
setBinary(base64String, "base64")  // Base64 문자열 → 바이너리
setBinaryBase64(base64String)      // Base64 축약형
setBinaryHex(hexString)            // Hex 문자열 → 바이너리
setBinaryFile("./relative.bin")    // 템플릿 디렉터리 기준 파일 읽기

Buffer 글로벌도 사용 가능합니다.

샘플 실행

동적 WAV 생성 (텍스트 길이 기반 무음 PCM):

ksgen -g human examples/human/input/beginner-translation.txt \
      examples/common/templates/binary-tts-silence-wav.js logs/tts-output.wav

토큰 시각화 BMP (코드 구조 핑거프린트):

ksgen -g javascript examples/javascript/input/source.js \
      examples/common/templates/binary-image-1x1-png.js logs/code-fingerprint.bmp

SVG 다이어그램 (함수 구조 → .svg → PNG 변환):

ksgen -g javascript examples/javascript/input/source.js \
      examples/common/templates/binary-document-pdf.js logs/code-structure.svg

# PNG 변환 (ImageMagick)
magick logs/code-structure.svg logs/code-structure.png

실제 TTS API 연결 예시

module.exports = function () {
    // 1. 소스에서 텍스트 추출
    var text = GLOBAL.source.tokens.map(function (t) { return t.token; }).join(" ");

    // 2. TTS API 호출 결과(Base64)를 setBinaryBase64 로 주입
    //    (실제 호출은 템플릿 외부 래퍼 스크립트에서 처리 후 JSON으로 전달)
    var ttsBase64 = GLOBAL.source.ttsResult; // 커스텀 필드
    setBinaryBase64(ttsBase64);

    writeln("TTS 결과 저장 완료: " + text.length + "자");
};

Java 프로젝트 샘플 (-d/-D) 실행 가이드

웹 가이드는 /cli-batch.html 에서 확인할 수 있습니다. 저장소 로컬 실행 시에는 브라우저에서 http://localhost:<port>/cli-batch.html 로 접근하면 됩니다.

샘플 프로젝트 위치:

examples/java/project-batch/
├─ BatchCliApp.java
├─ config/AppConfig.java
└─ service/ScoreReportService.java

함수 요약 템플릿으로 루트 파일만 분석:

node dist/bin/ksgen.js -d java examples/java/project-batch examples/java/templates/beginner-function-summary.js logs/demo-java-project-direct.md

함수 요약 템플릿으로 하위 폴더 전체 분석:

node dist/bin/ksgen.js -D java examples/java/project-batch examples/java/templates/beginner-function-summary.js logs/demo-java-project-recursive.md

보안 점검 템플릿 예시:

node dist/bin/ksgen.js -d java examples/java/project-batch examples/java/templates/security-risk-check.js logs/demo-java-project-security-direct.md
node dist/bin/ksgen.js -D java examples/java/project-batch examples/java/templates/security-risk-check.js logs/demo-java-project-security-recursive.md

보안 템플릿은 다음 패턴을 파일별로 누적 점검합니다.

• Runtime.getRuntime().exec
• ProcessBuilder
• System.getenv

-d/-D 동작 방식:

• 입력 source는 파일이 아니라 폴더입니다.
• -d는 지정한 폴더 바로 아래 파일만 대상으로 합니다.
• -D는 하위 폴더를 재귀적으로 내려가며 모든 파일을 대상으로 합니다.
• 내부적으로 각 파일에 대해 -g와 같은 파싱+템플릿 실행을 반복합니다.
• 결과는 파일별 구분선과 함께 하나의 output 파일에 순차적으로 누적됩니다.
• 일부 파일이 실패해도 가능한 파일은 계속 처리하고, 마지막에 실패 개수를 에러로 알려줍니다.

🧠 핵심 개념 (쉽게 이해하기)

Token

소스를 문법 단위(키워드, 식별자, 연산자 등)로 쪼갠 데이터입니다.

AST

Token을 의미 구조(함수, 변수, 호출 관계 등)로 재구성한 트리입니다.

Template

Token/AST를 입력으로 받아 원하는 출력(문서, 리포트, 코드)을 만드는 JavaScript 함수입니다.

🧩 템플릿 작성 기본

module.exports = function () {
    writeln("Hello ksgen");
};

사용 가능한 전역 객체

GLOBAL.source.language     // 언어
GLOBAL.source.sourceFile   // 소스 파일명
GLOBAL.source.tokens       // Token 배열
GLOBAL.source.variables    // AST Node 배열

출력 API

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 확인

메인 페이지 Demo 링크를 CLI로 실행하기

메인 페이지(public/index.html)의 Demo 링크는 query string으로 lang, source, template를 전달합니다. CLI에서는 같은 값을 그대로 -g 인자로 넣으면 동일한 결과를 재현할 수 있습니다.

실행 위치: 이 저장소 루트(현재 README가 있는 경로)

공통 형식:

ksgen -g <lang> examples/<source> examples/<template> logs/<output>.md

저장소 로컬 실행(패키지 미설치 환경):

node dist/bin/ksgen.js -g <lang> examples/<source> examples/<template> logs/<output>.md

메인 링크 기준 샘플 명령:

# Java 함수 요약
ksgen -g java examples/java/input/beginner-basics.java examples/java/templates/beginner-function-summary.js logs/demo-java-function-summary.md

# COBOL -> Java 변환
ksgen -g cobol examples/cobol/input/beginner-payroll.cob examples/cobol/templates/cobol-to-java.js logs/demo-cobol-to-java.md

# COBOL 산술/데이터 처리 분석
ksgen -g cobol examples/cobol/input/cobol-arithmetic-operations.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-arithmetic.md

# COBOL I/O 작업 분석
ksgen -g cobol examples/cobol/input/cobol-io-operations.cob examples/cobol/templates/cobol-structure-analysis.js logs/demo-cobol-io.md

# COBOL 제어 흐름 분석
ksgen -g cobol examples/cobol/input/cobol-control-flow.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-control.md

# COBOL 문자열 처리 분석
ksgen -g cobol examples/cobol/input/cobol-string-processing.cob examples/cobol/templates/cobol-structure-analysis.js logs/demo-cobol-string.md

# COBOL 테이블/배열 분석
ksgen -g cobol examples/cobol/input/cobol-table-arrays.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-arrays.md

# COBOL 서브프로그램 분석
ksgen -g cobol examples/cobol/input/cobol-subprograms.cob examples/cobol/templates/cobol-structure-analysis.js logs/demo-cobol-subprograms.md

# COBOL 파일/레코드 처리 분석
ksgen -g cobol examples/cobol/input/cobol-file-records.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-files.md

# COBOL 정렬/병합 분석
ksgen -g cobol examples/cobol/input/cobol-sort-merge.cob examples/cobol/templates/cobol-structure-analysis.js logs/demo-cobol-sort.md

# COBOL Embedded SQL 분석
ksgen -g cobol examples/cobol/input/cobol-embedded-sql.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-sql.md

# Oracle -> PostgreSQL 변환
ksgen -g sql examples/sql/input/beginner-orders.oracle examples/sql/templates/oracle_to_postgres.oracle.js logs/demo-oracle-to-postgres.md

# Oracle 고급 함수(10종) -> PostgreSQL 변환
ksgen -g sql examples/sql/input/oracle-advanced-functions.oracle examples/sql/templates/oracle_to_postgres.oracle.js logs/verify-oracle-to-postgres.md

# PostgreSQL 테이블/필드 추출
ksgen -g sql examples/sql/input/beginner-orders.postgresql examples/sql/templates/beginner-table-fields.postgresql.js logs/demo-postgresql-table-fields.md

# MSSQL 테이블/필드 추출
ksgen -g sql examples/sql/input/select.mssql examples/sql/templates/table-field-list.mssql.js logs/demo-mssql-table-fields.md

# MySQL 테이블/필드 추출
ksgen -g sql examples/sql/input/select.mysql examples/sql/templates/table-field-list.mysql.js logs/demo-mysql-table-fields.md

# Human 개인정보 검출
ksgen -g human examples/human/input/beginner-pii.txt examples/human/templates/pii-detection.js logs/demo-human-pii.md

# Human 금칙어 탐지
ksgen -g human examples/human/input/beginner-badwords.txt examples/human/templates/banned-words-detection.js logs/demo-human-badwords.md

# Human 번역 리포트
ksgen -g human examples/human/input/beginner-translation.txt examples/human/templates/translation-report.js logs/demo-human-translation.md

# Human 오타 검출/수정 제안
ksgen -g human examples/human/input/beginner-typo.txt examples/human/templates/typo-detection-fix.js logs/demo-human-typo.md

# HTML 링크/미디어/스크립트 URL 분석
ksgen -g html examples/html/input/link-analysis.html examples/html/templates/link-analysis-report.js logs/demo-html-link-analysis.md

# XML 태그/속성 요약
ksgen -g xml examples/xml/input/sample.xml examples/xml/templates/xml-tag-summary.js logs/demo-xml-tag-summary.md

# 문서 요약 (Markdown/TXT/Office/PDF/HWP)
ksgen -g document examples/document/input/sample-project-status.txt examples/document/templates/document-summary.js logs/demo-document-summary.md

# DOCX 문서 요약
ksgen -g document examples/document/input/sample-project-briefing.docx examples/document/templates/document-summary.js logs/demo-document-docx-summary.md

# PDF 문서 요약
ksgen -g document examples/document/input/sample-project-briefing.pdf examples/document/templates/document-summary.js logs/demo-document-pdf-summary.md

# DOCX 오타 검증
ksgen -g document examples/document/input/sample-project-briefing.docx examples/document/templates/typo-detection-fix.js logs/demo-document-docx-typo.md

# PDF 개인정보 검출
ksgen -g document examples/document/input/sample-project-briefing.pdf examples/document/templates/pii-detection.js logs/demo-document-pdf-pii.md

# TypeScript 요약
ksgen -g typescript examples/typescript/input/beginner-dashboard.ts examples/typescript/templates/beginner-ts-summary.js logs/demo-typescript-summary.md

# JSON Key 리포트
ksgen -g json examples/json/input/beginner-catalog.json examples/json/templates/json-key-report.js logs/demo-json-key-report.md

# YAML Key 리포트
ksgen -g yml examples/yml/input/beginner-deploy.yml examples/yml/templates/yml-key-report.js logs/demo-yml-key-report.md

# CSS Selector/Property 리포트
ksgen -g css examples/css/input/beginner-theme.css examples/css/templates/css-selector-report.js logs/demo-css-selector-report.md

📦 지원 언어

• C / C++
• Java
• Python
• JavaScript
• TypeScript
• COBOL
• HTML / XML / JSP
• Document (md, txt, doc, docx, xls, xlsx, ppt, pptx, pdf, hwp)
• JSON
• YAML (yml)
• CSS
• SQL (Oracle/MySQL/MSSQL/PostgreSQL)
• Human (자연어 텍스트)

문서 변환기 안내

• document 언어는 텍스트 문서(md, txt 등)를 기본 지원합니다.
• docx, pdf는 내장 변환 라이브러리를 우선 사용합니다.
• doc, xls, xlsx, ppt, pptx, hwp는 환경에 따라 LibreOffice 또는 hwp5txt/pdftotext가 필요할 수 있습니다.

확장자별 처리 방식

| 확장자 그룹 | 처리 방식 | 비고 | | --- | --- | --- | | md, markdown, txt, rst, adoc | 텍스트 직접 읽기 | 추가 도구 불필요 | | docx | 내장 변환기(mammoth) | 기본 동작 | | pdf | 내장 변환기(pdf-parse) 우선 | 실패 시 pdftotext 폴백 | | doc, xls, xlsx, ppt, pptx | 외부 도구 변환 | LibreOffice(soffice/libreoffice) 필요 | | hwp | 외부 도구 변환 | hwp5txt 권장, 필요 시 LibreOffice 폴백 |

OS별 설치 예시

# Windows (관리자 PowerShell)
winget install TheDocumentFoundation.LibreOffice
winget install Poppler.Poppler

# macOS (Homebrew)
brew install --cask libreoffice
brew install poppler

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libreoffice poppler-utils

# hwp 변환기(환경별 패키지명 상이)
hwp5txt --help

실행 파일 이름은 환경에 따라 soffice 또는 libreoffice로 다를 수 있습니다.

📋 COBOL 샘플 라이브러리

KSGen은 현대 COBOL 개발을 지원하기 위해 12개 카테고리의 전문적인 샘플을 제공합니다.

1️⃣ 연산 및 데이터 처리 (Arithmetic Operations)

파일: examples/cobol/input/cobol-arithmetic-operations.cob

COBOL의 기본 산술 연산과 계산:

• 기본 연산: MOVE, ADD, SUBTRACT, MULTIPLY, DIVIDE
• 복합 계산: COMPUTE
• 확장 옵션: GIVING (결과 보관), ROUNDED (반올림), ON SIZE ERROR (오버플로우 처리)

사용 예:

ksgen -g cobol examples/cobol/input/cobol-arithmetic-operations.cob examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-arithmetic.md

2️⃣ 입출력 작업 (I/O Operations)

파일: examples/cobol/input/cobol-io-operations.cob

화면 입출력과 파일 처리:

• 화면 I/O: DISPLAY, ACCEPT
• 파일 제어: OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, START
• 파일 모드: INPUT, OUTPUT, I-O, EXTEND
• 상태 코드: FILE STATUS 확인

3️⃣ 제어문 및 조건 처리 (Control Flow)

파일: examples/cobol/input/cobol-control-flow.cob

조건문, 반복문, 흐름 제어:

• 조건문: IF, ELSE, END-IF, EVALUATE, WHEN, OTHER
• 반복문: PERFORM, UNTIL, VARYING, END-PERFORM
• 논리 연산: AND, OR, NOT
• 흐름 제어: GO TO, EXIT, CONTINUE, STOP RUN
• 비교 연산자: =, >, <, >=, <=, <>

4️⃣ 문자열 처리 (String Processing)

파일: examples/cobol/input/cobol-string-processing.cob

문자열 조작 및 변환:

• STRING: 문자열 결합 (공백 제거, POINTER 위치 지정, OVERFLOW 처리)
• UNSTRING: 문자열 분해 (다중 구분자, 동적 분할)
• INSPECT: 문자열 검사 및 변환 (TALLYING, REPLACING, CONVERTING)

5️⃣ 테이블/배열 처리 (Table & Array Operations)

파일: examples/cobol/input/cobol-table-arrays.cob

배열 선언, 초기화, 접근:

• OCCURS: 배열 정의
• INDEXED BY: 인덱스 변수 자동 관리
• SET: 인덱스 조작 (TO, UP BY, DOWN BY)
• SEARCH: 순차 검색
• SEARCH ALL: 이진 검색 (정렬된 배열)

6️⃣ 서브프로그램 호출 (Subprograms)

파일: examples/cobol/input/cobol-subprograms.cob

프로그램 간 통신과 모듈화:

• CALL: 서브프로그램 호출
• USING: 매개변수 전달
• BY VALUE: 값 복사 (원본 보호)
• BY REFERENCE: 참조 전달 (원본 수정)
• RETURNING: 함수처럼 반환값 받기
• EXIT PROGRAM / GOBACK: 서브프로그램 종료

7️⃣ 파일 및 레코드 처리 (File & Record Operations)

파일: examples/cobol/input/cobol-file-records.cob

다양한 파일 조직과 접근 방식:

• SELECT/ASSIGN: 파일 정의
• ORGANIZATION: 순차(SEQUENTIAL), 인덱스(INDEXED), 상대(RELATIVE)
• ACCESS MODE: SEQUENTIAL, RANDOM, DYNAMIC
• RECORD KEY / ALTERNATE RECORD KEY: 주/보조 키 정의
• INVALID KEY / AT END: 예외 처리
• FILE STATUS: 작업 상태 코드

8️⃣ 정렬 및 병합 (Sort & Merge)

파일: examples/cobol/input/cobol-sort-merge.cob

대량 데이터 정렬과 병합:

• SORT: 단일 파일 정렬 (ASCENDING/DESCENDING)
• MERGE: 다중 정렬 파일 병합
• INPUT PROCEDURE: 정렬 전 데이터 필터링
• OUTPUT PROCEDURE: 정렬 후 결과 처리
• 다중 정렬 키: 우선순위 기반 정렬

9️⃣ 기타 주요 키워드 (Miscellaneous)

파일: examples/cobol/input/cobol-sort-merge.cob (포함)

유용한 추가 기능들:

• INITIALIZE: 변수 초기화
• SET: 조건 변수 설정
• COPY: 카피북 포함 (코드 재사용)
• DEBUGGING MODE: 프로덕션 제어 라인

🔟 Embedded SQL (SQL 포함)

파일: examples/cobol/input/cobol-embedded-sql.cob

데이터베이스 연동:

• CONNECT/DISCONNECT: DB 연결/해제
• SELECT INTO: 단일 행 조회
• CURSOR: 다중 행 조회 (DECLARE, OPEN, FETCH, CLOSE)
• INSERT/UPDATE/DELETE: 데이터 조작
• PREPARED STATEMENT: 동적 쿼리
• COMMIT/ROLLBACK: 트랜잭션 제어
• WHENEVER NOT FOUND: 조건부 처리
• SQLCODE: SQL 실행 결과 확인

🎯 활용 팁

배치 처리 (모든 COBOL 예제)

# 직접 하위 파일만 분석
ksgen -d cobol examples/cobol/input examples/cobol/templates/cobol-features-analysis.js logs/demo-cobol-batch.md

# 모든 하위 폴더 재귀 분석
ksgen -D cobol examples/cobol examples/cobol/templates/cobol-structure-analysis.js logs/demo-cobol-all.md

커스텀 템플릿 적용

각 카테고리별로 특화된 분석을 원할 경우, 템플릿을 직접 작성하여 다음과 같이 사용합니다:

ksgen -g cobol examples/cobol/input/<sample>.cob custom-templates/<your-template>.js logs/output.md

통합 분석 (다양한 언어 혼합)

# auto 옵션으로 언어 자동 판별 및 통합 분석
ksgen -D auto examples cobol-features-analysis.js logs/demo-integrated-analysis.md

🏁 마무리

ksgen은 단순히 코드를 파싱하는 도구가 아니라, 코드를 이해 가능한 산출물로 바꾸는 자동화 도구입니다.

특히 다음 목표가 있을 때 효과가 큽니다.

• 코드 문서화 자동화
• 구조 분석 표준화
• 반복 분석 업무 절감

📄 License

이 프로젝트는 MIT License를 따릅니다. 자세한 내용은 LICENSE 파일을 참고하세요.