react-dep-galaxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [scyprodigy]
+
+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

@@ -0,0 +1,129 @@
+# 🌌 React Galaxy
+
+> A React component dependency visualizer that turns your codebase into an interactive galaxy.
+
+[🚀 Live Demo](https://scyprodigy.github.io/react-galaxy/)
+
+---
+
+## 🖼️ Preview
+
+> Live demo: 12 components, node size represents line count, edges represent dependency direction.
+
+---
+
+## ✨ Features
+
+- 🧠 **Inspired by LLM Neuroanatomy**  
+  Visualize your component architecture as a neural network — spot shared components and dependency chains at a glance.
+
+- 📐 **Orthogonal Metrics (lines vs. dependencies)**  
+  Node size = line count; edge count = number of dependencies. Understand both scale and complexity in one view.
+
+- ⚡ **Real-time Interaction**  
+  Drag, zoom, hover to inspect component details (path, line count, dependency list), and click to trace dependency chains.
+
+---
+
+## 🚀 Quick Start
+
+### Using npx (no install required)
+
+```bash
+npx react-dep-galaxy scan ./src
+npx react-dep-galaxy view
+```
+
+### Global install
+
+```bash
+npm install -g react-dep-galaxy
+galaxy scan ./src
+galaxy view
+```
+
+Open your browser at `http://localhost:3000`
+
+> 💡 Running `scan` generates a `galaxy.json` file. `view` starts a local server that reads it.
+
+---
+
+## 📦 How It Works
+
+### 1️⃣ Scan Phase
+
+- Parses your React project (supports `.jsx`, `.tsx`, `.js`)
+- Detects function components and class components
+- Builds a component dependency graph from imports and JSX tag usage
+- Outputs `galaxy.json`
+
+### 2️⃣ View Phase
+
+- Starts a local HTTP server
+- Renders a force-directed graph using `vis-network`
+- Node size and color reflect line count and dependency depth
+
+---
+
+## 📁 Output Example
+
+```json
+[
+  {
+    "name": "App",
+    "path": "src/App.jsx",
+    "lines": 24,
+    "dependencies": ["Header", "MainContent", "Footer"]
+  }
+]
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/<your-username>/react-galaxy.git
+cd react-galaxy
+npm install
+npm link          # Links the `galaxy` command globally
+```
+
+---
+
+## 🚀 Deploy to GitHub Pages
+
+Static demo files are located in the `docs/` directory. To publish:
+
+1. Go to your repo → **Settings → Pages**
+2. Set Branch: `main`, Folder: `/docs`
+3. Click **Save**
+
+Your demo will be live at `https://[yourName].github.io/react-galaxy/` within a minute.
+
+---
+
+## 🤝 Contributing
+
+All contributions are welcome 🙌
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m "feat: add amazing feature"`
+4. Push the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+---
+
+## 🧭 Roadmap
+
+- [ ] Precise AST parsing (TypeScript, HOC support)
+- [ ] Plugin system (custom metrics and output formats)
+- [ ] AI-assisted analysis (LLM-powered component complexity detection)
+- [ ] Remote project analysis (upload code or link a GitHub repo)
+
+---
+
+## 📄 License
+
+MIT License © 2026 [scyprodigy]

package/README.zh-TW.md

@@ -0,0 +1,130 @@
+# 🌌 React Galaxy
+
+> A React component dependency visualizer that turns your codebase into an interactive galaxy.  
+> 一個將 React 元件依賴關係轉化為「星系圖」的可視化工具。
+
+[🚀 Live Demo](https://scyprodigy.github.io/react-galaxy/)
+
+---
+
+## 🖼️ Preview
+
+> 實際展示：12 個元件的依賴關係，節點大小代表程式碼行數，連線表示依賴方向。
+
+---
+
+## ✨ Features
+
+- 🧠 **Inspired by LLM Neuroanatomy**  
+  將元件架構視覺化為神經網絡般的結構，一眼看出共用元件與依賴鏈。
+
+- 📐 **Orthogonal Metrics（行數 vs 依賴數）**  
+  節點大小 ＝ 程式碼行數；連線數 ＝ 依賴數量。同時掌握規模與複雜度。
+
+- ⚡ **Real-time Interaction**  
+  拖曳、縮放；滑鼠懸停查看元件資訊（路徑、行數、依賴列表）；點擊追蹤依賴關係。
+
+---
+
+## 🚀 Quick Start
+
+### 使用 npx（無需安裝）
+
+```bash
+npx react-galaxy scan ./src
+npx react-galaxy view
+```
+
+### 本地安裝後使用
+
+```bash
+npm install -g react-galaxy
+galaxy scan ./src
+galaxy view
+```
+
+打開瀏覽器：`http://localhost:3000`
+
+> 💡 第一次執行 `scan` 會產生 `galaxy.json`，`view` 會啟動伺服器讀取該檔案。
+
+---
+
+## 📦 How It Works
+
+### 1️⃣ Scan Phase
+
+- 解析 React 專案（支援 `.jsx`、`.tsx`、`.js`）
+- 識別函式元件與類別元件
+- 建立元件依賴圖（基於 import 與 JSX 標籤）
+- 輸出 `galaxy.json`
+
+### 2️⃣ View Phase
+
+- 啟動本地 HTTP 伺服器
+- 使用 `vis-network` 渲染力導向圖
+- 節點大小、顏色對應行數與依賴數量
+
+---
+
+## 📁 Output Example
+
+```json
+[
+  {
+    "name": "App",
+    "path": "src/App.jsx",
+    "lines": 24,
+    "dependencies": ["Header", "MainContent", "Footer"]
+  }
+]
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/<你的用戶名>/react-galaxy.git
+cd react-galaxy
+npm install
+npm link          # 將指令 `galaxy` 連結到全域
+```
+
+---
+
+## 🚀 Deploy to GitHub Pages
+
+靜態展示檔案已放在 `docs/` 目錄，只需在倉庫設定中開啟 Pages：
+
+1. 進入倉庫 → **Settings → Pages**
+2. Branch: `main`，Folder: `/docs`
+3. 點擊 **Save**
+
+稍候一分鐘，即可透過 `https://[yourName].github.io/react-galaxy/` 訪問線上展示。
+
+---
+
+## 🤝 Contributing
+
+歡迎任何形式的貢獻 🙌
+
+1. Fork 本倉庫
+2. 建立新分支：`git checkout -b feature/amazing-feature`
+3. 提交修改：`git commit -m "feat: add amazing feature"`
+4. 推送分支：`git push origin feature/amazing-feature`
+5. 開啟 Pull Request
+
+---
+
+## 🧭 Roadmap
+
+- [ ] AST 精準解析（支援 TypeScript、HOC）
+- [ ] 插件系統（自訂指標、輸出格式）
+- [ ] AI 輔助分析（LLM 自動識別複雜元件）
+- [ ] 遠端專案分析（上傳程式碼或 GitHub 連結）
+
+---
+
+## 📄 License
+
+MIT License © 2026 [scyprodigy]

package/analyze-components.mjs

@@ -0,0 +1,261 @@
+/**
+ * analyze-components.mjs
+ *
+ * 使用 Babel 解析 React 專案中的 .jsx / .tsx 檔案，
+ * 輸出每個元件的名稱、路徑、行數與依賴列表。
+ *
+ * 用法：
+ *   node analyze-components.mjs [srcDir] [outputFile]
+ *
+ * 範例：
+ *   node analyze-components.mjs ./src galaxy.json
+ *
+ * 安裝依賴：
+ *   npm install @babel/parser @babel/traverse glob
+ */
+
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { glob } from "glob";
+
+// @babel/traverse 只有 CJS export，用 createRequire 載入
+const require = createRequire(import.meta.url);
+const parser = require("@babel/parser");
+const traverseModule = require("@babel/traverse");
+const traverse = traverseModule.default ?? traverseModule;
+
+// ─── 常數 ────────────────────────────────────────────────────────────────────
+
+const BABEL_PLUGINS = [
+  "jsx",
+  "typescript",
+  "classProperties",
+  "decorators-legacy",
+  "dynamicImport",
+  "optionalChaining",
+  "nullishCoalescingOperator",
+  "exportDefaultFrom",
+  "importAssertions",
+];
+
+// 只追蹤大寫開頭的標籤（React 元件慣例）
+const isComponentName = (name) => /^[A-Z]/.test(name);
+
+// ─── 解析單一檔案 ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} filePath  絕對路徑
+ * @param {string} rootDir   專案根目錄（用於計算相對路徑）
+ * @returns {Array<{name, path, lines, dependencies}>}
+ */
+function analyzeFile(filePath, rootDir) {
+  const source = fs.readFileSync(filePath, "utf-8");
+  const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+  const totalLines = source.split("\n").length;
+
+  let ast;
+  try {
+    ast = parser.parse(source, {
+      sourceType: "module",
+      plugins: BABEL_PLUGINS,
+      errorRecovery: true,
+    });
+  } catch (err) {
+    console.warn(`⚠️  無法解析 ${relativePath}：${err.message}`);
+    return [];
+  }
+
+  // ── 1. 收集所有 import 資訊 ──────────────────────────────────────────────
+  // importedNames: Set<string>  — 此檔案 import 的所有識別符
+  // importMap: Map<localName, source>
+  const importedNames = new Set();
+  const importMap = new Map(); // localName → import source
+
+  traverse(ast, {
+    ImportDeclaration({ node }) {
+      for (const specifier of node.specifiers) {
+        const local = specifier.local.name;
+        importedNames.add(local);
+        importMap.set(local, node.source.value);
+      }
+    },
+  });
+
+  // ── 2. 識別元件定義 ───────────────────────────────────────────────────────
+  // 收集每個元件：{ name, startLine, endLine, jsxTags: Set<string> }
+  const componentMap = new Map(); // name → component info
+
+  const registerComponent = (name, startLine, endLine) => {
+    if (!name || !isComponentName(name)) return;
+    if (!componentMap.has(name)) {
+      componentMap.set(name, {
+        name,
+        startLine,
+        endLine,
+        jsxTags: new Set(),
+      });
+    } else {
+      // 同名多次定義時，取最後一個（override / HOC pattern）
+      const existing = componentMap.get(name);
+      existing.startLine = startLine;
+      existing.endLine = endLine;
+    }
+  };
+
+  traverse(ast, {
+    // function Component() {} / export default function Component() {}
+    FunctionDeclaration({ node }) {
+      if (node.id) {
+        registerComponent(
+          node.id.name,
+          node.loc?.start.line,
+          node.loc?.end.line
+        );
+      }
+    },
+
+    // const Component = () => {} / const Component = function() {}
+    VariableDeclarator({ node }) {
+      if (
+        node.id?.type === "Identifier" &&
+        isComponentName(node.id.name) &&
+        (node.init?.type === "ArrowFunctionExpression" ||
+          node.init?.type === "FunctionExpression")
+      ) {
+        registerComponent(
+          node.id.name,
+          node.loc?.start.line,
+          node.loc?.end.line
+        );
+      }
+    },
+
+    // class Component extends React.Component / Component
+    ClassDeclaration({ node }) {
+      if (node.id) {
+        registerComponent(
+          node.id.name,
+          node.loc?.start.line,
+          node.loc?.end.line
+        );
+      }
+    },
+
+    // export default class / export default function
+    ExportDefaultDeclaration({ node }) {
+      const decl = node.declaration;
+      if (
+        (decl.type === "FunctionDeclaration" ||
+          decl.type === "ClassDeclaration") &&
+        decl.id
+      ) {
+        registerComponent(
+          decl.id.name,
+          decl.loc?.start.line,
+          decl.loc?.end.line
+        );
+      }
+    },
+  });
+
+  // ── 3. 收集 JSX 中使用的元件標籤 ─────────────────────────────────────────
+  // 策略：找出每個 JSXOpeningElement，判斷它屬於哪個元件定義的範圍
+  traverse(ast, {
+    JSXOpeningElement({ node }) {
+      let tagName = null;
+      if (node.name.type === "JSXIdentifier") {
+        tagName = node.name.name;
+      } else if (node.name.type === "JSXMemberExpression") {
+        // e.g. <UI.Button> → 取最外層物件名
+        let obj = node.name;
+        while (obj.type === "JSXMemberExpression") obj = obj.object;
+        tagName = obj.name;
+      }
+
+      if (!tagName || !isComponentName(tagName)) return;
+
+      const line = node.loc?.start.line ?? 0;
+
+      // 找最近包圍此 JSX 的元件
+      let bestComp = null;
+      for (const comp of componentMap.values()) {
+        if (
+          comp.startLine <= line &&
+          line <= comp.endLine &&
+          (!bestComp ||
+            comp.endLine - comp.startLine <
+              bestComp.endLine - bestComp.startLine)
+        ) {
+          bestComp = comp;
+        }
+      }
+
+      if (bestComp && tagName !== bestComp.name) {
+        bestComp.jsxTags.add(tagName);
+      }
+    },
+  });
+
+  // ── 4. 組合輸出 ───────────────────────────────────────────────────────────
+  const results = [];
+
+  for (const comp of componentMap.values()) {
+    // 依賴 = JSX 中使用且在 importedNames 裡的元件名稱
+    // （過濾掉同檔案內的輔助元件）
+    const dependencies = [...comp.jsxTags].filter((tag) =>
+      importedNames.has(tag)
+    );
+
+    results.push({
+      name: comp.name,
+      path: relativePath,
+      lines: (comp.endLine ?? totalLines) - (comp.startLine ?? 1) + 1,
+      dependencies: [...new Set(dependencies)].sort(),
+    });
+  }
+
+  return results;
+}
+
+// ─── 掃描目錄 ─────────────────────────────────────────────────────────────────
+
+async function analyzeProject(srcDir, outputFile) {
+  const absoluteSrc = path.resolve(srcDir);
+
+  console.log(`🔍  掃描目錄：${absoluteSrc}`);
+
+  const files = await glob("**/*.{js,jsx,ts,tsx}", {
+    cwd: absoluteSrc,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/__tests__/**", "**/*.test.*", "**/*.spec.*"],
+  });
+
+  console.log(`📄  找到 ${files.length} 個檔案`);
+
+  const allComponents = [];
+
+  for (const file of files) {
+    const components = analyzeFile(file, path.resolve("."));
+    allComponents.push(...components);
+  }
+
+  // 按元件名稱排序，方便閱讀
+  allComponents.sort((a, b) => a.name.localeCompare(b.name));
+
+  const json = JSON.stringify(allComponents, null, 2);
+
+  if (outputFile) {
+    fs.writeFileSync(outputFile, json, "utf-8");
+    console.log(`✅  輸出至 ${outputFile}（共 ${allComponents.length} 個元件）`);
+  } else {
+    console.log(json);
+  }
+
+  return allComponents;
+}
+
+// ─── CLI 入口 ─────────────────────────────────────────────────────────────────
+
+const [, , srcArg = "./src", outArg = "galaxy.json"] = process.argv;
+await analyzeProject(srcArg, outArg);

package/bin/galaxy.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..');
+
+const program = new Command();
+
+program
+  .name('galaxy')
+  .description('React component dependency visualizer')
+  .version('1.0.0');
+
+// ====== scan 指令 ======
+function scanProject(dir, outputFile = 'galaxy.json') {
+  const scriptPath = path.join(projectRoot, 'analyze-components.mjs');
+  const args = [scriptPath, dir, outputFile];
+
+  console.log(`🔍 掃描目錄：${dir} → 輸出 ${outputFile}`);
+
+  const child = spawn('node', args, { stdio: 'inherit' });
+
+  child.on('error', (err) => {
+    console.error(`❌ 無法執行掃描: ${err.message}`);
+  });
+
+  child.on('exit', (code) => {
+    if (code === 0) {
+      console.log(`✅ 掃描完成，結果已寫入 ${outputFile}`);
+    } else {
+      console.error(`❌ 掃描失敗，退出碼 ${code}`);
+    }
+  });
+}
+
+program
+  .command('scan <directory>')
+  .description('Scan a React project directory and generate galaxy.json')
+  .option('-o, --output <file>', 'output file name', 'galaxy.json')
+  .action((directory, options) => {
+    scanProject(directory, options.output);
+  });
+
+// ====== view 指令（可視化伺服器） ======
+program
+  .command('view')
+  .description('Start local viewer server')
+  .action(() => {
+    const port = 3000;
+    const galaxyJsonPath = path.join(process.cwd(), 'galaxy.json');
+
+    const server = http.createServer((req, res) => {
+      if (req.url === '/galaxy.json') {
+        // 提供 JSON 數據
+        fs.readFile(galaxyJsonPath, 'utf8', (err, data) => {
+          if (err) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'galaxy.json not found. Run `galaxy scan` first.' }));
+          } else {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(data);
+          }
+        });
+      } else {
+        // 提供 HTML 頁面
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>React Galaxy - Component Dependency</title>
+            <meta charset="utf-8">
+            <style>
+              body { margin: 0; padding: 0; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; }
+              #network { width: 100vw; height: 100vh; background: #0a0a1a; }
+              .info {
+                position: absolute;
+                bottom: 10px;
+                left: 10px;
+                background: rgba(0,0,0,0.7);
+                color: #ccc;
+                padding: 5px 10px;
+                border-radius: 5px;
+                font-size: 12px;
+                pointer-events: none;
+                z-index: 10;
+              }
+            </style>
+            <script type="text/javascript" src="https://unpkg.com/vis-network@9.1.2/dist/vis-network.min.js"></script>
+          </head>
+          <body>
+            <div id="network"></div>
+            <div class="info">
+              🌌 React Galaxy | 節點大小代表元件行數 | 邊表示依賴關係
+            </div>
+            <script>
+              fetch('/galaxy.json')
+                .then(res => res.json())
+                .then(data => {
+                  // 構建節點和邊
+                  const nodes = [];
+                  const edges = [];
+                  const nodeMap = new Map();
+
+                  data.forEach(comp => {
+                    const id = comp.name;
+                    nodeMap.set(id, {
+                      id: id,
+                      label: comp.name,
+                      title: \`路徑: \${comp.path}\\n行數: \${comp.lines}\\n依賴: \${comp.dependencies.join(', ') || '無'}\`,
+                      value: comp.lines,  // 用行數決定節點大小
+                    });
+                  });
+
+                  // 添加節點
+                  for (let node of nodeMap.values()) {
+                    nodes.push(node);
+                  }
+
+                  // 添加邊
+                  data.forEach(comp => {
+                    const from = comp.name;
+                    comp.dependencies.forEach(to => {
+                      if (nodeMap.has(to)) {
+                        edges.push({ from, to, arrows: 'to', smooth: { type: 'curvedCW' } });
+                      }
+                    });
+                  });
+
+                  const container = document.getElementById('network');
+                  const options = {
+                    nodes: {
+                      shape: 'dot',
+                      scaling: {
+                        min: 10,
+                        max: 60,
+                        label: { enabled: true, min: 12, max: 30 }
+                      },
+                      font: { color: '#ffffff', size: 14, face: 'monospace' },
+                      borderWidth: 2,
+                      shadow: true
+                    },
+                    edges: {
+                      color: { color: '#88aaff', highlight: '#ffaa88' },
+                      width: 2,
+                      smooth: { type: 'continuous', roundness: 0.5 },
+                      arrows: { to: { enabled: true, scaleFactor: 0.8 } }
+                    },
+                    physics: {
+                      stabilization: { iterations: 200 },
+                      barnesHut: { gravitationalConstant: -8000, centralGravity: 0.3, springLength: 150 }
+                    },
+                    interaction: {
+                      hover: true,
+                      tooltipDelay: 200,
+                      zoomView: true,
+                      dragView: true
+                    }
+                  };
+                  const network = new vis.Network(container, { nodes, edges }, options);
+                })
+                .catch(err => {
+                  console.error(err);
+                  document.body.innerHTML = '<h2 style="color:red;padding:20px">❌ 無法載入 galaxy.json，請先執行 <code>galaxy scan ./src</code></h2>';
+                });
+            </script>
+          </body>
+          </html>
+        `);
+      }
+    });
+
+    server.listen(port, () => {
+      console.log(`🚀 Galaxy Viewer 啟動：http://localhost:${port}`);
+      console.log(`📄 讀取數據：${galaxyJsonPath}`);
+      if (!fs.existsSync(galaxyJsonPath)) {
+        console.warn(`⚠️  找不到 galaxy.json，請先執行掃描。`);
+      }
+    });
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "react-dep-galaxy",
+  "version": "1.0.0",
+  "description": "Visualize React component dependencies as an interactive galaxy",
+  "type": "module",
+  "bin": {
+    "galaxy": "./bin/galaxy.js"
+  },
+  "files": [
+    "bin/",
+    "analyze-components.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@babel/parser": "^7.23.0",
+    "@babel/traverse": "^7.23.0",
+    "commander": "^12.0.0",
+    "glob": "^10.3.10"
+  }
+}