gitinsight-cli 0.1.0__py3-none-any.whl

gitinsight/git_reader.py

@@ -0,0 +1,225 @@
+"""
+git_reader.py — 从 Git 仓库提取完整提交记录与文件变更统计。
+
+输出:
+  - commits_df: 每行一条提交 (hash, author, email, datetime_str, message, insertions, deletions)
+  - file_stats_df: 每行一个文件变更 (hash, filepath, insertions, deletions)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Optional
+
+from loguru import logger
+from tqdm import tqdm
+
+import pandas as pd
+
+# 分隔符，用于区分每条提交
+_COMMIT_SEP = "---COMMIT_BOUNDARY---"
+
+_GIT_LOG_FORMAT = f"{_COMMIT_SEP}%n%H%n%an%n%ae%n%ad%n%s"
+
+
+def _count_commits(git_dir: str) -> Optional[int]:
+    """快速获取仓库的总提交数（用于进度条）。"""
+    try:
+        result = subprocess.run(
+            ["git", "-C", git_dir, "rev-list", "--all", "--count"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        if result.returncode == 0:
+            return int(result.stdout.strip())
+    except (FileNotFoundError, ValueError):
+        pass
+    return None
+
+
+def get_git_log(git_dir: str) -> Optional[str]:
+    """在指定 Git 目录中执行 git log 命令并返回输出文本，同时显示进度条。"""
+    import time
+    import hashlib
+    from pathlib import Path
+
+    if not os.path.exists(git_dir):
+        logger.error(f"❌ 错误：目录 '{git_dir}' 不存在。")
+        return None
+
+    # Determine cache file path
+    git_path = Path(git_dir).resolve()
+    if git_path.name == ".git":
+        git_path = git_path.parent
+
+    # Save cache to ~/.cache/gitinsight directory
+    cache_dir = Path.home() / ".cache" / "gitinsight"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # Use hash of the absolute path to generate unique cache filename
+    repo_hash = hashlib.md5(str(git_path).encode("utf-8")).hexdigest()[:12]
+    cache_path = cache_dir / f".git_log_{repo_hash}.cache"
+
+    # Check cache validity (1 day = 86400 seconds)
+    if cache_path.exists():
+        try:
+            mtime = cache_path.stat().st_mtime
+            if time.time() - mtime < 86400:
+                logger.info("✅ 发现有效的 Git 日志缓存，直接读取...")
+                with open(cache_path, "r", encoding="utf-8") as f:
+                    return f.read()
+            else:
+                logger.info("ℹ️ Git 日志缓存已过期，正在重新读取...")
+        except Exception as e:
+            logger.warning(f"⚠️ 读取缓存失败: {e}")
+
+    # 先获取总提交数，用于进度条
+    total_commits = _count_commits(git_dir)
+
+    try:
+        proc = subprocess.Popen(
+            [
+                "git",
+                "-C",
+                git_dir,
+                "log",
+                "--all",
+                f"--pretty=format:{_GIT_LOG_FORMAT}",
+                "--date=iso",
+                "--numstat",
+                "--no-color",
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        logger.error("❌ 错误：未找到 'git' 命令。请确保 Git 已安装并添加到 PATH。")
+        return None
+
+    # 逐行读取，遇到 COMMIT_SEP 时更新进度
+    lines: list[str] = []
+    with tqdm(
+        total=total_commits, desc="正在读取 Git 日志", unit="commit", leave=False
+    ) as pbar:
+        for line in proc.stdout:  # type: ignore[union-attr]
+            lines.append(line)
+            if _COMMIT_SEP in line:
+                pbar.update(1)
+
+    stderr_output = proc.stderr.read() if proc.stderr else ""  # type: ignore[union-attr]
+    proc.wait()
+
+    if proc.returncode != 0:
+        logger.error(f"❌ Git 命令执行失败：{stderr_output}")
+        logger.error(f"   仓库路径：{os.path.abspath(git_dir)}")
+        logger.error("   请确认这是一个有效的 Git 仓库。")
+        return None
+
+    result = "".join(lines)
+
+    # Save to cache
+    try:
+        with open(cache_path, "w", encoding="utf-8") as f:
+            f.write(result)
+        logger.info(f"✅ Git 日志已缓存至: {cache_path}")
+    except Exception as e:
+        logger.warning(f"⚠️ 写入缓存失败: {e}")
+
+    return result
+
+
+# numstat 行的正则: <insertions>\t<deletions>\t<filepath>
+# 二进制文件显示为 -\t-\tfilepath
+_NUMSTAT_RE = re.compile(r"^(\d+|-)\t(\d+|-)\t(.+)$")
+
+
+def parse_git_log(stdout: str) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    将 git log --numstat 输出解析为两个 DataFrame。
+
+    Returns:
+        commits_df: 每条提交一行
+        file_stats_df: 每个文件变更一行
+    """
+    commits: list[dict] = []
+    file_stats: list[dict] = []
+
+    blocks = stdout.split(_COMMIT_SEP)
+
+    for block in tqdm(blocks, desc="正在解析提交记录", unit="commit", leave=False):
+        block = block.strip()
+        if not block:
+            continue
+
+        lines = block.split("\n")
+        # 前5行: hash, author, email, date, message
+        if len(lines) < 5:
+            continue
+
+        commit_hash = lines[0].strip()
+        author = lines[1].strip()
+        email = lines[2].strip()
+        datetime_str = lines[3].strip()
+        message = lines[4].strip()
+
+        total_ins = 0
+        total_del = 0
+
+        # 从第5行开始是 numstat（可能有空行间隔）
+        for i in range(5, len(lines)):
+            line = lines[i].strip()
+            if not line:
+                continue
+            m = _NUMSTAT_RE.match(line)
+            if m:
+                ins_str, del_str, filepath = m.groups()
+                ins = int(ins_str) if ins_str != "-" else 0
+                dels = int(del_str) if del_str != "-" else 0
+                total_ins += ins
+                total_del += dels
+                file_stats.append(
+                    {
+                        "hash": commit_hash,
+                        "filepath": filepath,
+                        "insertions": ins,
+                        "deletions": dels,
+                    }
+                )
+
+        commits.append(
+            {
+                "hash": commit_hash,
+                "author": author,
+                "email": email,
+                "datetime_str": datetime_str,
+                "message": message,
+                "insertions": total_ins,
+                "deletions": total_del,
+            }
+        )
+
+    commits_df = pd.DataFrame(
+        commits,
+        columns=[
+            "hash",
+            "author",
+            "email",
+            "datetime_str",
+            "message",
+            "insertions",
+            "deletions",
+        ],
+    )
+    file_stats_df = pd.DataFrame(
+        file_stats,
+        columns=["hash", "filepath", "insertions", "deletions"],
+    )
+
+    return commits_df, file_stats_df

gitinsight/report.py

@@ -0,0 +1,26 @@
+"""
+report.py — 控制台摘要输出。
+"""
+from __future__ import annotations
+
+from typing import Dict
+
+
+def print_summary(
+    metrics: Dict[str, object],
+    filter_stats,
+    outputs: Dict[str, str],
+) -> None:
+    print("\n" + "=" * 50)
+    print(" Git 项目人员分析报告摘要")
+    print("=" * 50)
+    print(f"总提交次数: {metrics.get('total_commits', 0):,} (过滤前 {filter_stats.before:,}, 过滤掉 {filter_stats.removed:,} 条自动化提交)")
+    print(f"参与开发者: {metrics.get('total_authors', 0)} 人")
+    print(f"活跃开发者(近半年): {metrics.get('active_authors_6m', 0)} 人")
+    print(f"代码净增长: {metrics.get('net_lines', 0):+,} 行")
+    print(f"项目生命周期: {metrics.get('project_lifecycle_days', 0):,} 天")
+    print(f"数据范围: {metrics.get('date_range', '无')}")
+    print("-" * 50)
+    print("[产出文件]")
+    print(f"  可视化仪表板: {outputs.get('html', '')}")
+    print("=" * 50)

gitinsight_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: gitinsight-cli
+Version: 0.1.0
+Summary: A powerful collection of Git repository analysis tools and visualizations.
+Project-URL: Homepage, https://github.com/Rain-kl/GitInsight
+Project-URL: Bug Tracker, https://github.com/Rain-kl/GitInsight/issues
+Author-email: Ryan <ryan@arctel.net>
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: pyecharts>=2.0.0
+Requires-Dist: tqdm>=4.67.3
+Description-Content-Type: text/markdown
+
+# GitInsight
+
+GitRepository Analysis and Visualization Tool / Git 仓库分析与可视化工具
+
+<!-- PROJECT SHIELDS -->
+
+[![MIT License][license-shield]][license-url]
+
+[![Python Version][python-version]][python-version]
+
+---
+
+## 目录
+
+- [GitInsight](#gitinsight)
+  - [目录](#目录)
+    - [上手指南](#上手指南)
+          - [开发前的配置要求](#开发前的配置要求)
+          - [**安装步骤**](#安装步骤)
+    - [文件目录说明](#文件目录说明)
+    - [开发的架构](#开发的架构)
+    - [部署](#部署)
+    - [使用到的框架](#使用到的框架)
+    - [贡献者](#贡献者)
+      - [如何参与开源项目](#如何参与开源项目)
+
+### 上手指南
+
+###### 开发前的配置要求
+
+1. Python >= 3.12
+2. uv (推荐使用 uv 进行包管理) 或 pip
+
+###### **安装步骤**
+
+1. Clone the repo
+
+```sh
+git clone https://github.com/Rain-kl/GitInsight.git
+cd GitInsight
+```
+
+2. Install as a command-line tool
+
+```sh
+# Install from PyPI
+uv tool install gitinsight-cli
+
+# Install from the current checkout
+uv tool install .
+
+# Or install directly from GitHub
+uv tool install git+https://github.com/Rain-kl/GitInsight.git
+```
+
+3. Run the tool
+
+```sh
+gitinsight /path/to/git/repository
+```
+
+Upgrade or uninstall the tool:
+
+```sh
+uv tool upgrade gitinsight-cli
+uv tool uninstall gitinsight-cli
+```
+
+For local development:
+
+```sh
+uv sync
+uv run gitinsight /path/to/git/repository
+```
+
+### 文件目录说明
+
+```
+GitInsight
+├── .github/             # GitHub 配置
+├── gitinsight/          # 源代码目录
+│   ├── __init__.py
+│   ├── __main__.py      # 程序入口
+│   ├── analysis.py      # 分析逻辑 (Pandas)
+│   ├── charts.py        # 图表绘制 (Pyecharts)
+│   ├── dashboard.py     # 仪表盘展示
+│   ├── git_reader.py    # Git日志读取
+│   └── report.py        # 报告生成
+├── .gitignore
+├── pyproject.toml       # 项目配置与依赖
+├── uv.lock              # 依赖锁定文件
+└── README.md            # 项目说明
+```
+
+### 开发的架构
+
+本项目主要由数据读取、数据分析、图表生成和仪表盘展示四个部分组成。
+- `git_reader.py`: 负责读取 Git 仓库的提交日志。
+- `analysis.py`: 使用 Pandas 对日志数据进行清洗和统计分析。
+- `charts.py`: 使用 Pyecharts 生成各类可视化图表。
+- `dashboard.py`: 整合图表生成 HTML 仪表盘。
+
+请阅读架构文档(如有)查阅为该项目的架构。
+
+### 部署
+
+本项目为 Python 命令行工具，可直接本地运行或打包发布到 PyPI。
+暂无特殊部署部署。
+
+### 使用到的框架
+
+- [Pandas](https://pandas.pydata.org/) - Data structures and analysis tools
+- [Pyecharts](https://github.com/pyecharts/pyecharts) - Python Echarts Plotting Library
+- [Loguru](https://github.com/Delgan/loguru) - Python logging made (stupidly) simple
+- [Hatchling](https://hatch.pypa.io/latest/) - Modern, extensible Python build backend
+
+### 贡献者
+
+请阅读**CONTRIBUTING.md** 查阅为该项目做出贡献的开发者。
+
+#### 如何参与开源项目
+
+贡献使开源社区成为一个学习、激励和创造的绝佳场所。你所作的任何贡献都是**非常感谢**的。
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<!-- links -->
+[license-shield]: https://img.shields.io/github/license/shaojintian/Best_README_template.svg?style=flat-square
+[license-url]: https://github.com/Rain-kl/GitInsight/blob/main/LICENSE
+[python-version]:https://img.shields.io/pypi/pyversions/pandas

gitinsight_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gitinsight/__init__.py,sha256=6AWu5_EtfXYnu5jSCbcTnIFO8o7LYUbYpudTiP72l6M,100
+gitinsight/__main__.py,sha256=EjOIyLp410y4XDHLbAlNurcNWl4za2C-53xNnWnUTVk,2715
+gitinsight/analysis.py,sha256=FDVRqfxeALcwwJ1rwIHG1At-iPHpXKXfJQJKS3o449I,17351
+gitinsight/charts.py,sha256=DISuXRS-vwNDJ3a_B52lUl2oLcZZbm1hUzVNvBxmWWY,30485
+gitinsight/dashboard.py,sha256=u0-ebljtj8G7U1cnuoBrVDQXBJLMkg3NAZEnOlc4wuk,18519
+gitinsight/git_reader.py,sha256=h5YScSixNnNFXhRe0PP16nhj8w1wIpdwwqHWDWu0U_I,6857
+gitinsight/report.py,sha256=v-WRm_slXs3ZRXPk0WmQpIZ4vQRpt3PsE1EeN_a-NO8,969
+gitinsight_cli-0.1.0.dist-info/METADATA,sha256=TNggyRshYyWDaYSJ_sfvoyVHXE85iJvys92J99F9-7o,4444
+gitinsight_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gitinsight_cli-0.1.0.dist-info/entry_points.txt,sha256=mUsNFsZ6tKoM-0W2GCGHVSTDJlYGVtgfdDPhOpe_Ru8,56
+gitinsight_cli-0.1.0.dist-info/RECORD,,

gitinsight_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gitinsight_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitinsight = gitinsight.__main__:main