openspec-stat 1.0.0

package/README.md

@@ -0,0 +1,234 @@
+# openspec-stat
+
+[![NPM version](https://img.shields.io/npm/v/openspec-stat.svg?style=flat)](https://npmjs.com/package/openspec-stat)
+[![NPM downloads](http://img.shields.io/npm/dm/openspec-stat.svg?style=flat)](https://npmjs.com/package/openspec-stat)
+
+A CLI tool for tracking team members' OpenSpec proposals and code changes in Git repositories.
+
+## Features
+
+- ✅ Track Git commits within specified time ranges
+- ✅ Identify commits containing both OpenSpec proposals and code changes
+- ✅ Group statistics by author (commits, proposals, code changes)
+- ✅ Support multiple branches and wildcard filtering
+- ✅ Author name mapping (handle multiple Git accounts for the same person)
+- ✅ Track only recently active members (default: 2 weeks)
+- ✅ Multiple output formats: Table, JSON, CSV, Markdown
+- ✅ Internationalization support: English and Chinese (简体中文)
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g openspec-stat
+# or
+pnpm add -g openspec-stat
+```
+
+### Local Project Installation
+
+```bash
+npm install openspec-stat --save-dev
+# or
+pnpm add -D openspec-stat
+```
+
+## Usage
+
+### Basic Usage
+
+Run in a Git repository directory:
+
+```bash
+openspec-stat
+```
+
+This will track commits in the default time range (yesterday 20:00 ~ today 20:00).
+
+### Command Line Options
+
+```bash
+openspec-stat [options]
+
+Options:
+  -r, --repo <path>           Repository path (default: current directory)
+  -b, --branches <branches>   Branch list, comma-separated (e.g., origin/master,origin/release/v1.0)
+  -s, --since <datetime>      Start time (default: yesterday 20:00)
+  -u, --until <datetime>      End time (default: today 20:00)
+  -a, --author <name>         Filter by specific author
+  --json                      Output in JSON format
+  --csv                       Output in CSV format
+  --markdown                  Output in Markdown format
+  -c, --config <path>         Configuration file path
+  -v, --verbose               Verbose output mode
+  -l, --lang <language>       Language for output (en, zh-CN) (default: "en")
+  -V, --version               Display version number
+  -h, --help                  Display help information
+```
+
+### Examples
+
+```bash
+# Track default time range
+openspec-stat
+
+# Track specific time range
+openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
+
+# Track specific branches
+openspec-stat --branches "origin/master,origin/release/v1.0"
+
+# Track specific author
+openspec-stat --author "John Doe"
+
+# Output JSON format
+openspec-stat --json > stats.json
+
+# Output Markdown report
+openspec-stat --markdown > report.md
+
+# Verbose output mode
+openspec-stat --verbose
+
+# Use custom configuration file
+openspec-stat --config ./my-config.json
+
+# Use Chinese output
+openspec-stat --lang zh-CN
+
+# Combine with other options
+openspec-stat --lang zh-CN --verbose
+```
+
+## Configuration File
+
+Create `.openspec-stats.json` or `openspec-stats.config.json` in the project root:
+
+```json
+{
+  "defaultBranches": [
+    "origin/master",
+    "origin/main",
+    "origin/release/*"
+  ],
+  "defaultSinceHours": -30,
+  "defaultUntilHours": 18,
+  "authorMapping": {
+    "John Doe": "John Doe",
+    "john.doe@company.com": "John Doe",
+    "johnd": "John Doe"
+  },
+  "openspecDir": "openspec/",
+  "excludeExtensions": [
+    ".md",
+    ".txt",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".webp"
+  ],
+  "activeUserWeeks": 2
+}
+```
+
+### Configuration Options
+
+- **defaultBranches**: Default branches to track (supports wildcards)
+- **defaultSinceHours**: Default start time offset (hours, negative means going back)
+- **defaultUntilHours**: Default end time (hour of the day)
+- **authorMapping**: Author name mapping to unify multiple Git accounts for the same person
+- **openspecDir**: OpenSpec proposals directory (default: `openspec/`)
+- **excludeExtensions**: File extensions to exclude (not counted as code changes)
+- **activeUserWeeks**: Active user time window (weeks, default: 2)
+
+## Statistics Logic
+
+The tool identifies commits that meet both conditions:
+
+1. Contains file changes in the `openspec/` directory (OpenSpec proposals)
+2. Contains code file changes (excluding documentation files)
+
+Statistics include:
+
+- **Commits**: Total number of qualifying commits
+- **OpenSpec Proposals**: Counted by `openspec/changes/{proposal-name}` directories
+- **Code Files**: Number of modified code files
+- **Additions**: Lines of code added
+- **Deletions**: Lines of code deleted
+- **Net Changes**: Additions - Deletions
+
+## Output Formats
+
+### Table Format (Default)
+
+```
+📊 OpenSpec Statistics Report
+Time Range: 2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
+Branches: origin/master
+Total Commits: 15
+
+┌──────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
+│ Author   │ Commits │ OpenSpec Proposals│ Code Files │ Additions │ Deletions │ Net Changes │
+├──────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
+│ John Doe │ 8       │ 3                │ 45         │ +1234     │ -567      │ +667        │
+│ Jane S.  │ 7       │ 2                │ 32         │ +890      │ -234      │ +656        │
+└──────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
+```
+
+### JSON Format
+
+```bash
+openspec-stat --json
+```
+
+### CSV Format
+
+```bash
+openspec-stat --csv > stats.csv
+```
+
+### Markdown Format
+
+```bash
+openspec-stat --markdown > report.md
+```
+
+## Language Support
+
+The tool supports both English and Chinese output. You can specify the language using the `--lang` option:
+
+```bash
+# English output (default)
+openspec-stat --lang en
+
+# Chinese output
+openspec-stat --lang zh-CN
+```
+
+The tool will also automatically detect your system language. If your system locale is set to Chinese, the output will default to Chinese.
+
+For a Chinese version of this README, see [README.zh-CN.md](./README.zh-CN.md).
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development mode
+pnpm dev
+
+# Build
+pnpm build
+
+# Local testing
+node dist/esm/cli.js
+```
+
+## LICENSE
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,234 @@
+# openspec-stat
+
+[![NPM version](https://img.shields.io/npm/v/openspec-stat.svg?style=flat)](https://npmjs.com/package/openspec-stat)
+[![NPM downloads](http://img.shields.io/npm/dm/openspec-stat.svg?style=flat)](https://npmjs.com/package/openspec-stat)
+
+用于追踪团队成员在 Git 仓库中的 OpenSpec 提案和代码变更的命令行工具。
+
+[English](./README.md) | 简体中文
+
+## 功能特性
+
+- ✅ 追踪指定时间范围内的 Git 提交
+- ✅ 识别同时包含 OpenSpec 提案和代码变更的提交
+- ✅ 按作者分组统计（提交数、提案数、代码变更）
+- ✅ 支持多分支和通配符过滤
+- ✅ 作者名称映射（处理同一人的多个 Git 账号）
+- ✅ 仅追踪最近活跃的成员（默认：2 周）
+- ✅ 多种输出格式：表格、JSON、CSV、Markdown
+- ✅ 国际化支持：英文和中文
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g openspec-stat
+# 或
+pnpm add -g openspec-stat
+```
+
+### 本地项目安装
+
+```bash
+npm install openspec-stat --save-dev
+# 或
+pnpm add -D openspec-stat
+```
+
+## 使用方法
+
+### 基本用法
+
+在 Git 仓库目录中运行：
+
+```bash
+openspec-stat
+```
+
+这将追踪默认时间范围内的提交（昨天 20:00 ~ 今天 20:00）。
+
+### 命令行选项
+
+```bash
+openspec-stat [选项]
+
+选项：
+  -r, --repo <path>           仓库路径（默认：当前目录）
+  -b, --branches <branches>   分支列表，逗号分隔（例如：origin/master,origin/release/v1.0）
+  -s, --since <datetime>      开始时间（默认：昨天 20:00）
+  -u, --until <datetime>      结束时间（默认：今天 20:00）
+  -a, --author <name>         按特定作者筛选
+  --json                      以 JSON 格式输出
+  --csv                       以 CSV 格式输出
+  --markdown                  以 Markdown 格式输出
+  -c, --config <path>         配置文件路径
+  -v, --verbose               详细输出模式
+  -l, --lang <language>       输出语言（en, zh-CN）（默认："en"）
+  -V, --version               显示版本号
+  -h, --help                  显示帮助信息
+```
+
+### 使用示例
+
+```bash
+# 追踪默认时间范围
+openspec-stat
+
+# 追踪特定时间范围
+openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
+
+# 追踪特定分支
+openspec-stat --branches "origin/master,origin/release/v1.0"
+
+# 追踪特定作者
+openspec-stat --author "张三"
+
+# 输出 JSON 格式
+openspec-stat --json > stats.json
+
+# 输出 Markdown 报告
+openspec-stat --markdown > report.md
+
+# 详细输出模式
+openspec-stat --verbose
+
+# 使用自定义配置文件
+openspec-stat --config ./my-config.json
+
+# 使用中文输出
+openspec-stat --lang zh-CN
+
+# 组合多个选项
+openspec-stat --lang zh-CN --verbose
+```
+
+## 配置文件
+
+在项目根目录创建 `.openspec-stats.json` 或 `openspec-stats.config.json`：
+
+```json
+{
+  "defaultBranches": [
+    "origin/master",
+    "origin/main",
+    "origin/release/*"
+  ],
+  "defaultSinceHours": -30,
+  "defaultUntilHours": 18,
+  "authorMapping": {
+    "张三": "张三",
+    "zhangsan@company.com": "张三",
+    "zs": "张三"
+  },
+  "openspecDir": "openspec/",
+  "excludeExtensions": [
+    ".md",
+    ".txt",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".webp"
+  ],
+  "activeUserWeeks": 2
+}
+```
+
+### 配置选项说明
+
+- **defaultBranches**：默认追踪的分支（支持通配符）
+- **defaultSinceHours**：默认开始时间偏移（小时，负数表示往前推）
+- **defaultUntilHours**：默认结束时间（当天的小时数）
+- **authorMapping**：作者名称映射，用于统一同一人的多个 Git 账号
+- **openspecDir**：OpenSpec 提案目录（默认：`openspec/`）
+- **excludeExtensions**：排除的文件扩展名（不计入代码变更）
+- **activeUserWeeks**：活跃用户时间窗口（周，默认：2）
+
+## 统计逻辑
+
+工具会识别同时满足以下两个条件的提交：
+
+1. 包含 `openspec/` 目录中的文件变更（OpenSpec 提案）
+2. 包含代码文件变更（排除文档文件）
+
+统计内容包括：
+
+- **提交数**：符合条件的提交总数
+- **OpenSpec 提案**：按 `openspec/changes/{提案名称}` 目录统计
+- **代码文件**：修改的代码文件数量
+- **新增行数**：新增的代码行数
+- **删除行数**：删除的代码行数
+- **净变更**：新增行数 - 删除行数
+
+## 输出格式
+
+### 表格格式（默认）
+
+```
+📊 OpenSpec 统计报告
+时间范围：2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
+分支：origin/master
+总提交数：15
+
+┌──────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
+│ 作者     │ 提交数  │ 提案数           │ 代码文件   │ 新增行数  │ 删除行数  │ 净变更      │
+├──────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
+│ 张三     │ 8       │ 3                │ 45         │ +1234     │ -567      │ +667        │
+│ 李四     │ 7       │ 2                │ 32         │ +890      │ -234      │ +656        │
+└──────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
+```
+
+### JSON 格式
+
+```bash
+openspec-stat --json
+```
+
+### CSV 格式
+
+```bash
+openspec-stat --csv > stats.csv
+```
+
+### Markdown 格式
+
+```bash
+openspec-stat --markdown > report.md
+```
+
+## 语言支持
+
+工具支持英文和中文输出。您可以使用 `--lang` 选项指定语言：
+
+```bash
+# 英文输出（默认）
+openspec-stat --lang en
+
+# 中文输出
+openspec-stat --lang zh-CN
+```
+
+工具还会自动检测您的系统语言。如果您的系统区域设置为中文，输出将默认使用中文。
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发模式
+pnpm dev
+
+# 构建
+pnpm build
+
+# 本地测试
+node dist/esm/cli.js
+```
+
+## 许可证
+
+MIT

package/dist/cjs/branch-selector.d.ts

@@ -0,0 +1,7 @@
+export interface BranchInfo {
+    name: string;
+    lastCommitDate: Date;
+    commitCount: number;
+}
+export declare function getActiveBranches(repoPath: string, limit?: number): Promise<BranchInfo[]>;
+export declare function selectBranches(repoPath: string, defaultBranches?: string[]): Promise<string[]>;

package/dist/cjs/branch-selector.js

@@ -0,0 +1,124 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/branch-selector.ts
+var branch_selector_exports = {};
+__export(branch_selector_exports, {
+  getActiveBranches: () => getActiveBranches,
+  selectBranches: () => selectBranches
+});
+module.exports = __toCommonJS(branch_selector_exports);
+var import_prompts = require("@inquirer/prompts");
+var import_simple_git = __toESM(require("simple-git"));
+var import_chalk = __toESM(require("chalk"));
+var import_i18n = require("./i18n/index.js");
+async function getActiveBranches(repoPath, limit = 10) {
+  const git = (0, import_simple_git.default)(repoPath);
+  const branches = await git.branch(["-r"]);
+  const branchNames = branches.all.filter((b) => !b.includes("HEAD"));
+  const branchInfos = [];
+  for (const branchName of branchNames) {
+    try {
+      const log = await git.log({
+        "--max-count": "1",
+        [branchName]: null
+      });
+      if (log.latest) {
+        branchInfos.push({
+          name: branchName,
+          lastCommitDate: new Date(log.latest.date),
+          commitCount: 0
+        });
+      }
+    } catch (error) {
+      continue;
+    }
+  }
+  branchInfos.sort((a, b) => b.lastCommitDate.getTime() - a.lastCommitDate.getTime());
+  return branchInfos.slice(0, limit);
+}
+async function selectBranches(repoPath, defaultBranches) {
+  console.log(import_chalk.default.blue((0, import_i18n.t)("branch.fetching")));
+  const activeBranches = await getActiveBranches(repoPath, 10);
+  if (activeBranches.length === 0) {
+    console.log(import_chalk.default.yellow((0, import_i18n.t)("warning.noBranches")));
+    return defaultBranches || [];
+  }
+  const choices = activeBranches.map((branch) => ({
+    name: `${branch.name} (${(0, import_i18n.t)("branch.lastCommit", { date: branch.lastCommitDate.toLocaleDateString() })})`,
+    value: branch.name,
+    checked: false
+  }));
+  choices.push({
+    name: import_chalk.default.gray((0, import_i18n.t)("branch.customSeparator")),
+    value: "__custom__",
+    checked: false
+  });
+  const mode = await (0, import_prompts.select)({
+    message: (0, import_i18n.t)("branch.selectMode"),
+    choices: [
+      { name: (0, import_i18n.t)("branch.mode.select"), value: "select" },
+      { name: (0, import_i18n.t)("branch.mode.default"), value: "default" },
+      { name: (0, import_i18n.t)("branch.mode.custom"), value: "custom" }
+    ]
+  });
+  if (mode === "default") {
+    return defaultBranches || [];
+  }
+  if (mode === "custom") {
+    const customInput = await (0, import_prompts.input)({
+      message: (0, import_i18n.t)("branch.customInput"),
+      default: (defaultBranches == null ? void 0 : defaultBranches.join(", ")) || ""
+    });
+    return customInput.split(",").map((b) => b.trim()).filter((b) => b);
+  }
+  const selected = await (0, import_prompts.checkbox)({
+    message: (0, import_i18n.t)("branch.selectPrompt"),
+    choices: choices.slice(0, -1),
+    pageSize: 15
+  });
+  if (selected.length > 0) {
+    console.log(import_chalk.default.green((0, import_i18n.t)("branch.selected")));
+    selected.forEach((branch) => {
+      console.log(import_chalk.default.green(`  • ${branch}`));
+    });
+  }
+  if (selected.includes("__custom__")) {
+    const customInput = await (0, import_prompts.input)({
+      message: (0, import_i18n.t)("branch.additionalInput")
+    });
+    const customBranches = customInput.split(",").map((b) => b.trim()).filter((b) => b);
+    return [...selected.filter((b) => b !== "__custom__"), ...customBranches];
+  }
+  return selected.length > 0 ? selected : defaultBranches || [];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getActiveBranches,
+  selectBranches
+});

package/dist/cjs/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};