openspec-stat 1.4.3 → 1.4.5

package/README.md

@@ -10,279 +10,127 @@ English | [简体中文](./README.zh-CN.md)
 
 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
-- ✅ **Proposal-based statistics summary** - Aggregate statistics by proposal to avoid merge commit bias
-- ✅ 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 (简体中文)
-- ✅ **🆕 Multi-repository mode (BETA)** - Analyze multiple local/remote repositories in one run
-
-## Installation
-
-### Global Installation
+## Install
 
 ```bash
+# global install
 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
+# or local (dev dependency)
+npm install -D openspec-stat
 ```
 
-## Usage
-
-### Basic Usage
+## Quick start
 
-Run in a Git repository directory:
+Default window: yesterday 20:00 → today 20:00.
 
 ```bash
+# basic run
 openspec-stat
-```
-
-This will track commits in the default time range (yesterday 20:00 ~ today 20:00).
-
-### Multi-Repository Mode (BETA)
-
-⚠️ **Experimental Feature**: Multi-repository mode allows analyzing multiple repositories (local or remote) in a single run.
 
-```bash
-# Initialize multi-repo configuration (interactive wizard)
-openspec-stat init --multi
+# custom time range
+openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
 
-# Run multi-repo analysis
+# multi-repo (uses config)
 openspec-stat multi -c .openspec-stats.multi.json
-
-# Run with detailed contributor statistics
-openspec-stat multi -c .openspec-stats.multi.json --show-contributors
-
-# Generate template
-openspec-stat init --template multi -o config.json
 ```
 
-**Perfect for team managers who:**
-- Have local access to backend repos but not frontend repos
-- Need to track contributions across multiple repositories
-- Want combined statistics without running multiple commands
+## Key features
 
-**Note**: By default, multi-repo mode only shows aggregated statistics to avoid information overload. Use `--show-contributors` to see detailed statistics for each contributor.
+- Track Git commits in a time window and per-branch filters
+- Detect commits containing both OpenSpec proposals and code changes
+- Proposal-based aggregation to avoid merge-commit bias
+- Author grouping with name mapping (multiple Git identities per person)
+- Multi-branch wildcards and **multi-repository mode (BETA)**
+- Outputs: table, JSON, CSV, Markdown; languages: en / zh-CN
 
-See [Multi-Repository Guide](./MULTI_REPO_GUIDE.md) for detailed documentation.
+## Common flags (full list: `openspec-stat --help`)
 
-### Command Line Options
+- `-r, --repo <path>`: repository path (default: current directory)
+- `-b, --branches <list>`: comma-separated branches, supports wildcards
+- `-s, --since <datetime>` / `-u, --until <datetime>`: time window
+- `-a, --author <name>`: filter by author
+- `-c, --config <path>`: config file
+- `--json | --csv | --markdown`: output format
+- `-l, --lang <language>`: `en` or `zh-CN`
+- `-v, --verbose`: verbose output
 
-```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
-```
+## Multi-repo mode (BETA)
 
-### Examples
+Analyze multiple local/remote repositories in one run.
 
 ```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
+openspec-stat init --multi                         # interactive setup
+openspec-stat multi -c .openspec-stats.multi.json  # aggregated view
+openspec-stat multi -c .openspec-stats.multi.json --show-contributors
+```
 
-# Use Chinese output
-openspec-stat --lang zh-CN
+See [Multi-Repository Guide](./MULTI_REPO_GUIDE.md) for full details.
 
-# Combine with other options
-openspec-stat --lang zh-CN --verbose
-```
+**Remote cache**: remote repos are cloned once and reused under
+`~/.openspec-stat/cached/repos/<repo-name>-<hash>`. Use `--cache-mode temporary`
+to force one-off clones, or `--force-clone` to refresh a single run.
 
-## Configuration File
+## Configuration (short)
 
-Create `.openspec-stats.json` or `openspec-stats.config.json` in the project root:
+Create `.openspec-stats.json` or `openspec-stats.config.json` in the repo root.
 
 ```json
 {
-  "defaultBranches": [
-    "origin/master",
-    "origin/main",
-    "origin/release/*"
-  ],
+  "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"
-  },
+  "authorMapping": {"john.doe@company.com": "John Doe"},
   "openspecDir": "openspec/",
-  "excludeExtensions": [
-    ".md",
-    ".txt",
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".gif",
-    ".svg",
-    ".ico",
-    ".webp"
-  ],
+  "excludeExtensions": [".md", ".txt", ".png", ".jpg", "..."],
   "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
-
-The tool provides two perspectives:
+Key fields: default branches/time window, author mapping (merge identities), OpenSpec directory, excluded extensions, active user window.
 
-1. **Proposal Summary**: Aggregates statistics by proposal, showing total code changes per proposal and all contributors. This avoids statistical bias from merge commits.
-2. **Author Summary**: Groups statistics by contributor, showing individual author contributions.
-
-## Output Formats
-
-### Table Format (Default)
+## Output
 
 ```
-📊 OpenSpec Statistics Report
-Time Range: 2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
+📊 OpenSpec Report
+Time: 2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
 Branches: origin/master
-Total Commits: 15
-
-📋 Proposal Summary (by proposal)
-┌──────────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ Proposal     │ Commits │ Contributors     │ Code Files │ Additions │ Deletions │ Net Changes │
-├──────────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
-│ feature-123  │ 5       │ John Doe, Jane S.│ 30         │ +890      │ -234      │ +656        │
-│ feature-456  │ 3       │ John Doe         │ 15         │ +344      │ -100      │ +244        │
-└──────────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
-  📊 Total: 2 proposals | 8 commits | 45 files | +1234/-334 lines (net: +900)
-
-👥 Author Summary (by contributor)
-┌──────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ 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
+Total Commits: 8
+
+Proposal Summary
+┌──────────────┬─────────┬───────────┬───────────┐
+│ Proposal     │ Commits │ Files     │ Net Δ     │
+├──────────────┼─────────┼───────────┼───────────┤
+│ feature-123  │ 5       │ 30        │ +656      │
+└──────────────┴─────────┴───────────┴───────────┘
+
+Author Summary
+┌─────────┬─────────┬───────────┬───────────┐
+│ Author  │ Commits │ Proposals │ Net Δ     │
+├─────────┼─────────┼───────────┼───────────┤
+│ John D. │ 8       │ 3         │ +667      │
+└─────────┴─────────┴───────────┴───────────┘
 ```
 
-## Language Support
+Use `--markdown`, `--json`, or `--csv` for other formats.
 
-The tool supports both English and Chinese output. You can specify the language using the `--lang` option:
+## Language
 
-```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).
+`--lang en` (default) or `--lang zh-CN`. Locale-based auto-detection is also supported.
 
 ## Development
 
 ```bash
-# Install dependencies
 pnpm install
-
-# Development mode
 pnpm dev
-
-# Build
 pnpm build
-
-# Local testing
 node dist/cjs/cli.js
 ```
 
 ## Contributing & Release Process
 
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, branching, and pull-request expectations.
-- See [RELEASE.md](./RELEASE.md) for the Changesets-driven versioning and publishing workflow.
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and PR expectations.
+- See [RELEASE.md](./RELEASE.md) for the Changesets-driven publishing workflow.
 
-## LICENSE
+## License
 
 MIT