github-mobile-reader 0.1.1 → 0.1.2

package/README.ko.md

@@ -40,9 +40,13 @@ data
 
 - **의존성 제로 코어** — 파서는 Node.js ≥ 18이 있는 어디서나 동작합니다
 - **이중 출력 포맷** — CJS (`require`)와 ESM (`import`) 모두 지원, TypeScript 타입 포함
+- **CLI** — `npx github-mobile-reader --repo owner/repo --pr 42` 로 어떤 PR이든 즉시 변환
 - **GitHub Action** — 레포에 YAML 파일 하나만 추가하면 PR마다 Reader 문서가 자동 생성됩니다
+- **파일별 분리 출력** — 변경된 JS/TS 파일마다 독립적인 섹션으로 출력
+- **JSX/Tailwind 인식** — `.jsx`/`.tsx` 파일은 컴포넌트 트리(`🎨 JSX Structure`)와 Tailwind 클래스 diff(`💅 Style Changes`)를 별도 섹션으로 분리 출력
 - **양방향 diff 추적** — 추가된 코드와 삭제된 코드를 각각 별도 섹션으로 표시
 - **보수적 설계** — 패턴이 애매할 때는 잘못된 정보를 보여주는 대신 덜 보여줍니다
+- **보안 기본값** — 토큰은 `$GITHUB_TOKEN` 환경변수로만 읽음 — 셸 히스토리나 `ps` 목록에 노출되는 `--token` 플래그 없음
 
 ---
 
@@ -50,13 +54,75 @@ data
 
 1. [빠른 시작](#빠른-시작)
 2. [언어 지원](#언어-지원)
-3. [GitHub Action (권장)](#github-action-권장)
-4. [npm 라이브러리 사용법](#npm-라이브러리-사용법)
-5. [출력 형식](#출력-형식)
-6. [API 레퍼런스](#api-레퍼런스)
-7. [파서 동작 원리](#파서-동작-원리)
-8. [기여하기](#기여하기)
-9. [라이선스](#라이선스)
+3. [CLI 사용법](#cli-사용법)
+4. [GitHub Action (권장)](#github-action-권장)
+5. [npm 라이브러리 사용법](#npm-라이브러리-사용법)
+6. [출력 형식](#출력-형식)
+7. [API 레퍼런스](#api-레퍼런스)
+8. [파서 동작 원리](#파서-동작-원리)
+9. [기여하기](#기여하기)
+10. [라이선스](#라이선스)
+
+---
+
+## CLI 사용법
+
+터미널에서 `github-mobile-reader`를 바로 실행할 수 있습니다 — 별도 설정 파일 불필요. GitHub에서 PR diff를 받아 모바일 친화적인 Markdown으로 변환하고 `./reader-output/`에 PR별로 파일을 저장합니다.
+
+### 인증 (토큰 설정)
+
+CLI 실행 **전에** 환경변수로 GitHub 토큰을 설정하세요:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxx
+npx github-mobile-reader --repo owner/repo --pr 42
+```
+
+> **보안 안내:** CLI는 `--token` 플래그를 지원하지 않습니다. 커맨드라인 인자로 시크릿을 전달하면 셸 히스토리와 `ps` 출력에 토큰이 노출됩니다. 반드시 환경변수를 사용하세요.
+
+### 단일 PR
+
+```bash
+npx github-mobile-reader --repo owner/repo --pr 42
+```
+
+### 최근 PR 전체
+
+```bash
+npx github-mobile-reader --repo owner/repo --all
+```
+
+### 옵션
+
+| 플래그      | 기본값             | 설명                                                    |
+| ----------- | ------------------ | ------------------------------------------------------- |
+| `--repo`    | *(필수)*           | `owner/repo` 형식의 레포지토리                          |
+| `--pr`      | —                  | 특정 PR 번호 하나 처리                                  |
+| `--all`     | —                  | 최근 PR 전체 처리 (`--limit`와 함께 사용)               |
+| `--out`     | `./reader-output`  | 생성된 `.md` 파일 저장 경로 — 상대 경로만 허용, `..` 불가 |
+| `--limit`   | `10`               | `--all` 사용 시 가져올 PR 최대 개수                     |
+
+토큰: `$GITHUB_TOKEN` 환경변수에서 읽음 (미인증 시 60 req/hr, 인증 시 5 000 req/hr).
+
+### 출력 결과
+
+PR마다 `reader-output/pr-<번호>.md` 파일 하나가 생성됩니다.
+
+JSX/TSX 파일은 추가 섹션이 생성됩니다:
+
+```
+# 📖 PR #42 — My Feature
+
+## 📄 `src/App.tsx`
+
+### 🧠 Logical Flow   ← JS 로직 트리
+### 🎨 JSX Structure  ← 컴포넌트 계층 구조 (JSX/TSX 전용)
+### 💅 Style Changes  ← 추가/제거된 Tailwind 클래스 (JSX/TSX 전용)
+### ✅ Added Code
+### ❌ Removed Code
+```
+
+> **참고:** `reader-output/`는 기본적으로 `.gitignore`에 포함되어 있습니다 — 생성된 파일은 로컬에만 저장되며 레포지토리에 커밋되지 않습니다.
 
 ---
 
@@ -487,8 +553,10 @@ github-mobile-reader/
 │   ├── parser.ts     ← 핵심 diff → logical flow 파서
 │   ├── index.ts      ← npm 공개 API
 │   ├── action.ts     ← GitHub Action 진입점
+│   ├── cli.ts        ← CLI 진입점 (npx github-mobile-reader)
 │   └── test.ts       ← 스모크 테스트 (33개)
 ├── dist/             ← 컴파일 결과물 (자동 생성, 수정 금지)
+├── reader-output/    ← CLI 출력 디렉토리 (gitignore됨)
 ├── .github/
 │   └── workflows/
 │       └── mobile-reader.yml   ← 사용자용 예시 워크플로우

package/README.md

@@ -38,9 +38,13 @@ data
 
 - **Zero-dependency core** — the parser runs anywhere Node.js ≥ 18 is available
 - **Dual output format** — CJS (`require`) and ESM (`import`) with full TypeScript types
+- **CLI** — `npx github-mobile-reader --repo owner/repo --pr 42` fetches and converts any PR instantly
 - **GitHub Action** — drop one YAML block into any repo and get auto-generated Reader docs on every PR
+- **File-by-file output** — each changed JS/TS file gets its own independent section in the output
+- **JSX/Tailwind aware** — `.jsx`/`.tsx` files get a component tree (`🎨 JSX Structure`) and a Tailwind class diff (`💅 Style Changes`) instead of one unreadable blob
 - **Tracks both sides of a diff** — shows added _and_ removed code in separate sections
 - **Conservative by design** — when a pattern is ambiguous, the library shows less rather than showing something wrong
+- **Secure by default** — token is read from `$GITHUB_TOKEN` only; no flag that leaks to shell history or `ps`
 
 ---
 
@@ -48,13 +52,14 @@ data
 
 1. [Quick Start](#quick-start)
 2. [Language Support](#language-support)
-3. [GitHub Action (recommended)](#github-action-recommended)
-4. [npm Library Usage](#npm-library-usage)
-5. [Output Format](#output-format)
-6. [API Reference](#api-reference)
-7. [How the Parser Works](#how-the-parser-works)
-8. [Contributing](#contributing)
-9. [License](#license)
+3. [CLI Usage](#cli-usage)
+4. [GitHub Action (recommended)](#github-action-recommended)
+5. [npm Library Usage](#npm-library-usage)
+6. [Output Format](#output-format)
+7. [API Reference](#api-reference)
+8. [How the Parser Works](#how-the-parser-works)
+9. [Contributing](#contributing)
+10. [License](#license)
 
 ---
 
@@ -129,6 +134,67 @@ If you'd like to contribute an adapter for your language, see [Contributing](#co
 
 ---
 
+## CLI Usage
+
+Run `github-mobile-reader` directly from your terminal — no setup, no config file. It fetches a PR diff from GitHub, converts it to mobile-friendly Markdown, and saves one file per PR to `./reader-output/`.
+
+### Authentication
+
+Set your GitHub token as an environment variable **before** running the CLI:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxx
+npx github-mobile-reader --repo owner/repo --pr 42
+```
+
+> **Security note:** The CLI does not accept a `--token` flag. Passing secrets as command-line arguments exposes them in shell history and `ps` output. Always use the environment variable.
+
+### Single PR
+
+```bash
+npx github-mobile-reader --repo owner/repo --pr 42
+```
+
+### All recent PRs
+
+```bash
+npx github-mobile-reader --repo owner/repo --all
+```
+
+### Options
+
+| Flag      | Default           | Description                                       |
+| --------- | ----------------- | ------------------------------------------------- |
+| `--repo`  | *(required)*      | Repository in `owner/repo` format                 |
+| `--pr`    | —                 | Process a single PR by number                     |
+| `--all`   | —                 | Process all recent PRs (use with `--limit`)       |
+| `--out`   | `./reader-output` | Output directory — relative paths only, no `..`   |
+| `--limit` | `10`              | Max number of PRs to fetch when using `--all`     |
+
+Token: read from `$GITHUB_TOKEN` environment variable (60 req/hr unauthenticated, 5 000 req/hr authenticated).
+
+### Output
+
+Each PR produces one file: `reader-output/pr-<number>.md`.
+
+Inside that file, every changed JS/TS file gets its own section. JSX/TSX files get two extra sections:
+
+```
+# 📖 PR #42 — My Feature
+
+## 📄 `src/App.tsx`
+
+### 🧠 Logical Flow   ← JS logic tree
+### 🎨 JSX Structure  ← component hierarchy (JSX/TSX only)
+### 💅 Style Changes  ← added/removed Tailwind classes (JSX/TSX only)
+### ✅ Added Code
+### ❌ Removed Code
+```
+
+> **Note:** `reader-output/` is gitignored by default — the generated files are local only and not committed to your repository.
+
+---
+
 ## Quick Start
 
 ```bash
@@ -482,8 +548,10 @@ github-mobile-reader/
 ├── src/
 │   ├── parser.ts     ← core diff → logical flow parser
 │   ├── index.ts      ← public npm API surface
-│   └── action.ts     ← GitHub Action entry point
+│   ├── action.ts     ← GitHub Action entry point
+│   └── cli.ts        ← CLI entry point (npx github-mobile-reader)
 ├── dist/             ← compiled output (auto-generated, do not edit)
+├── reader-output/    ← CLI output directory (gitignored)
 ├── .github/
 │   └── workflows/
 │       └── mobile-reader.yml   ← example workflow for consumers

package/dist/action.js

@@ -28,6 +28,131 @@ var path = __toESM(require("path"));
 var import_child_process = require("child_process");
 
 // src/parser.ts
+function isJSXFile(filename) {
+  return /\.(jsx|tsx)$/.test(filename);
+}
+function hasJSXContent(lines) {
+  return lines.some((l) => /<[A-Z][A-Za-z]*[\s/>]/.test(l) || /return\s*\(/.test(l));
+}
+function isClassNameOnlyLine(line) {
+  return /^className=/.test(line.trim());
+}
+function extractClassName(line) {
+  const staticMatch = line.match(/className="([^"]*)"/);
+  if (staticMatch) return staticMatch[1];
+  const ternaryMatch = line.match(/className=\{[^?]+\?\s*"([^"]*)"\s*:\s*"([^"]*)"\}/);
+  if (ternaryMatch) return `${ternaryMatch[1]} ${ternaryMatch[2]}`;
+  const templateMatch = line.match(/className=\{`([^`]*)`\}/);
+  if (templateMatch) {
+    const raw = templateMatch[1];
+    const literals = raw.replace(/\$\{[^}]*\}/g, " ").trim();
+    const exprStrings = [...raw.matchAll(/"([^"]*)"/g)].map((m) => m[1]);
+    return [literals, ...exprStrings].filter(Boolean).join(" ");
+  }
+  return null;
+}
+function extractComponentFromLine(line) {
+  const tagMatch = line.match(/<([A-Za-z][A-Za-z0-9.]*)/);
+  if (tagMatch) return tagMatch[1];
+  return "unknown";
+}
+function parseClassNameChanges(addedLines, removedLines) {
+  const componentMap = /* @__PURE__ */ new Map();
+  for (const line of addedLines.filter((l) => /className=/.test(l))) {
+    const cls = extractClassName(line);
+    const comp = extractComponentFromLine(line);
+    if (!cls) continue;
+    if (!componentMap.has(comp)) componentMap.set(comp, { added: /* @__PURE__ */ new Set(), removed: /* @__PURE__ */ new Set() });
+    cls.split(/\s+/).filter(Boolean).forEach((c) => componentMap.get(comp).added.add(c));
+  }
+  for (const line of removedLines.filter((l) => /className=/.test(l))) {
+    const cls = extractClassName(line);
+    const comp = extractComponentFromLine(line);
+    if (!cls) continue;
+    if (!componentMap.has(comp)) componentMap.set(comp, { added: /* @__PURE__ */ new Set(), removed: /* @__PURE__ */ new Set() });
+    cls.split(/\s+/).filter(Boolean).forEach((c) => componentMap.get(comp).removed.add(c));
+  }
+  const changes = [];
+  for (const [comp, { added, removed }] of componentMap) {
+    const pureAdded = [...added].filter((c) => !removed.has(c));
+    const pureRemoved = [...removed].filter((c) => !added.has(c));
+    if (pureAdded.length === 0 && pureRemoved.length === 0) continue;
+    changes.push({ component: comp, added: pureAdded, removed: pureRemoved });
+  }
+  return changes;
+}
+function renderStyleChanges(changes) {
+  const lines = [];
+  for (const change of changes) {
+    lines.push(`**${change.component}**`);
+    if (change.added.length > 0) lines.push(`  + ${change.added.join("  ")}`);
+    if (change.removed.length > 0) lines.push(`  - ${change.removed.join("  ")}`);
+  }
+  return lines;
+}
+function isJSXElement(line) {
+  const t = line.trim();
+  return /^<[A-Za-z]/.test(t) || /^<\/[A-Za-z]/.test(t);
+}
+function isJSXClosing(line) {
+  return /^<\/[A-Za-z]/.test(line.trim());
+}
+function isJSXSelfClosing(line) {
+  return /\/>[\s]*$/.test(line.trim());
+}
+function extractJSXComponentName(line) {
+  const trimmed = line.trim();
+  const closingMatch = trimmed.match(/^<\/([A-Za-z][A-Za-z0-9.]*)/);
+  if (closingMatch) return `/${closingMatch[1]}`;
+  const nameMatch = trimmed.match(/^<([A-Za-z][A-Za-z0-9.]*)/);
+  if (!nameMatch) return trimmed;
+  const name = nameMatch[1];
+  const eventProps = [];
+  for (const m of trimmed.matchAll(/\b(on[A-Z]\w+)=/g)) {
+    eventProps.push(m[1]);
+  }
+  return eventProps.length > 0 ? `${name}(${eventProps.join(", ")})` : name;
+}
+function shouldIgnoreJSX(line) {
+  const t = line.trim();
+  return isClassNameOnlyLine(t) || /^style=/.test(t) || /^aria-/.test(t) || /^data-/.test(t) || /^strokeLinecap=/.test(t) || /^strokeLinejoin=/.test(t) || /^strokeWidth=/.test(t) || /^viewBox=/.test(t) || /^fill=/.test(t) || /^stroke=/.test(t) || /^d="/.test(t) || t === "{" || t === "}" || t === "(" || t === ")" || t === "<>" || t === "</>" || /^\{\/\*/.test(t);
+}
+function parseJSXToFlowTree(lines) {
+  const roots = [];
+  const stack = [];
+  for (const line of lines) {
+    if (!isJSXElement(line)) continue;
+    if (shouldIgnoreJSX(line)) continue;
+    const depth = getIndentDepth(line);
+    if (isJSXClosing(line)) {
+      while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+        stack.pop();
+      }
+      continue;
+    }
+    const name = extractJSXComponentName(line);
+    const selfClosing = isJSXSelfClosing(line);
+    const node = {
+      type: "call",
+      name,
+      children: [],
+      depth,
+      priority: 5 /* OTHER */
+    };
+    while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+      stack.pop();
+    }
+    if (stack.length === 0) {
+      roots.push(node);
+    } else {
+      stack[stack.length - 1].node.children.push(node);
+    }
+    if (!selfClosing) {
+      stack.push({ node, depth });
+    }
+  }
+  return roots;
+}
 function filterDiffLines(diffText) {
   const lines = diffText.split("\n");
   const added = lines.filter((l) => l.startsWith("+") && !l.startsWith("+++") && l.trim() !== "+").map((l) => l.substring(1));
@@ -201,19 +326,21 @@ function renderFlowTree(nodes, indent = 0) {
   }
   return lines;
 }
-function parseDiffToLogicalFlow(diffText) {
+function generateReaderMarkdown(diffText, meta = {}) {
   const { added, removed } = filterDiffLines(diffText);
-  const normalizedAdded = normalizeCode(added);
+  const isJSX = Boolean(
+    meta.file && isJSXFile(meta.file) || hasJSXContent(added)
+  );
+  const addedForFlow = isJSX ? added.filter((l) => !isClassNameOnlyLine(l)) : added;
+  const normalizedAdded = normalizeCode(addedForFlow);
   const flowTree = parseToFlowTree(normalizedAdded);
-  return {
-    root: flowTree,
-    rawCode: added.join("\n"),
-    removedCode: removed.join("\n")
-  };
-}
-function generateReaderMarkdown(diffText, meta = {}) {
-  const result = parseDiffToLogicalFlow(diffText);
+  const rawCode = addedForFlow.join("\n");
+  const removedForCode = isJSX ? removed.filter((l) => !isClassNameOnlyLine(l)) : removed;
+  const removedCode = removedForCode.join("\n");
+  const classNameChanges = isJSX ? parseClassNameChanges(added, removed) : [];
+  const jsxTree = isJSX ? parseJSXToFlowTree(added) : [];
   const sections = [];
+  const lang = isJSX ? "tsx" : "typescript";
   sections.push("# \u{1F4D6} GitHub Reader View\n");
   sections.push("> Generated by **github-mobile-reader**");
   if (meta.repo) sections.push(`> Repository: ${meta.repo}`);
@@ -221,22 +348,33 @@ function generateReaderMarkdown(diffText, meta = {}) {
   if (meta.commit) sections.push(`> Commit: \`${meta.commit}\``);
   if (meta.file) sections.push(`> File: \`${meta.file}\``);
   sections.push("\n");
-  if (result.root.length > 0) {
+  if (flowTree.length > 0) {
     sections.push("## \u{1F9E0} Logical Flow\n");
     sections.push("```");
-    sections.push(...renderFlowTree(result.root));
+    sections.push(...renderFlowTree(flowTree));
     sections.push("```\n");
   }
-  if (result.rawCode.trim()) {
+  if (isJSX && jsxTree.length > 0) {
+    sections.push("## \u{1F3A8} JSX Structure\n");
+    sections.push("```");
+    sections.push(...renderFlowTree(jsxTree));
+    sections.push("```\n");
+  }
+  if (isJSX && classNameChanges.length > 0) {
+    sections.push("## \u{1F485} Style Changes\n");
+    sections.push(...renderStyleChanges(classNameChanges));
+    sections.push("");
+  }
+  if (rawCode.trim()) {
     sections.push("## \u2705 Added Code\n");
-    sections.push("```typescript");
-    sections.push(result.rawCode);
+    sections.push(`\`\`\`${lang}`);
+    sections.push(rawCode);
     sections.push("```\n");
   }
-  if (result.removedCode.trim()) {
+  if (removedCode.trim()) {
     sections.push("## \u274C Removed Code\n");
-    sections.push("```typescript");
-    sections.push(result.removedCode);
+    sections.push(`\`\`\`${lang}`);
+    sections.push(removedCode);
     sections.push("```\n");
   }
   sections.push("---");