gstatx 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 📊 Export statistics from git repositories
 
-A CLI tool to analyze and export statistics from one or multiple git repositories.
+A CLI tool and library to analyze and export statistics from one or multiple git repositories.
 
 ## Installation
 
@@ -10,10 +10,10 @@ A CLI tool to analyze and export statistics from one or multiple git repositorie
 npm install -g gstatx
 ```
 
-Or using npm:
+Or install as a library:
 
 ```bash
-npm install -g gstatx
+npm install gstatx
 ```
 
 ## Quick Start
@@ -27,6 +27,12 @@ gstatx contributors ./repo1 ./repo2 ./repo3
 
 # Hide commit counts
 gstatx contributors --no-commits ./my-repo
+
+# Generate commit history report
+gstatx hist ./my-repo
+
+# Generate history report for last month and save to file
+gstatx hist --since "1 month ago" --out report.json ./my-repo
 ```
 
 ## User Guide
@@ -39,7 +45,7 @@ List contributors for specified git repositories.
 
 **Usage:**
 ```bash
-gstatx contributors [options] <repo-path> [repo-path2 ...]
+gstatx contributors [options] [repo-paths...]
 ```
 
 **Options:**
@@ -56,8 +62,49 @@ gstatx contributors --no-commits ./my-repo
 
 # List contributors for multiple repositories
 gstatx contributors ./repo1 ./repo2 ./repo3
+
+# Use repositories from config file
+gstatx contributors
+```
+
+#### `hist`
+
+Generate commit history report with detailed statistics.
+
+**Usage:**
+```bash
+gstatx hist [options] [repo-paths...]
 ```
 
+**Options:**
+- `-s, --since <date>` - Start date for the report (e.g., "2024-01-01", "1 month ago")
+- `-u, --until <date>` - End date for the report (e.g., "2024-12-31", "now")
+- `-o, --out <file>` - Output file path (defaults to stdout)
+- `--help, -h` - Show help message
+
+**Examples:**
+```bash
+# Generate history for a repository
+gstatx hist ./my-repo
+
+# Generate history for last month
+gstatx hist --since "1 month ago" ./my-repo
+
+# Generate history for specific period
+gstatx hist --since "2024-01-01" --until "2024-12-31" ./my-repo
+
+# Save to file
+gstatx hist --since "1 month ago" --out report.json ./my-repo
+
+# Use repositories from config file
+gstatx hist --since "1 month ago" --out report.json
+```
+
+The report includes:
+- Commit details (hash, author, date, message)
+- File-level statistics (files changed, insertions, deletions)
+- Summary statistics per repository
+
 ### Configuration File
 
 You can create a `.gstatxrc.json` file to set default options and repository paths. The config file is automatically searched in the current directory and parent directories.
@@ -85,7 +132,6 @@ You can create a `.gstatxrc.json` file to set default options and repository pat
 ```
 
 **Configuration Fields:**
-
 - `contributors.no-commits` (boolean, optional): Hide commit counts by default
 - `cloneIfNotExists` (boolean, optional): Automatically clone repositories that don't exist locally
 - `repositories` (array, optional): List of repositories to process
@@ -97,6 +143,7 @@ You can create a `.gstatxrc.json` file to set default options and repository pat
 - Repository paths in the config file are resolved relative to the `.gstatxrc.json` file location, not the current working directory
 - If `cloneIfNotExists: true` and a repository doesn't exist, it will be cloned from the `url`
 - CLI arguments always override config file values
+- Both `contributors` and `hist` commands can use repositories from the config file
 
 **Example Config File:**
 
@@ -125,6 +172,7 @@ You can create a `.gstatxrc.json` file to set default options and repository pat
 
 - `--help, -h` - Show help message
 - `--config, -c <path>` - Specify custom config file path
+- `--version, -V` - Show version number
 
 **Examples:**
 ```bash
@@ -133,6 +181,9 @@ gstatx --config ./custom-config.json contributors
 
 # Short form
 gstatx -c ./custom-config.json contributors
+
+# Show version
+gstatx --version
 ```
 
 ### Using Config File Repositories
@@ -142,6 +193,9 @@ If you have repositories defined in your config file, you can run commands witho
 ```bash
 # Uses repositories from .gstatxrc.json
 gstatx contributors
+
+# Generate history for all config repositories
+gstatx hist --since "1 month ago" --out report.json
 ```
 
 The tool will automatically use the repositories listed in your config file.
@@ -171,6 +225,76 @@ When `cloneIfNotExists: true` is set in your config:
 
 Running `gstatx contributors` will automatically clone the repository if it doesn't exist.
 
+## Library Usage
+
+gstatx can also be used as a library in your TypeScript/JavaScript projects.
+
+### Installation
+
+```bash
+npm install gstatx
+```
+
+### Basic Usage
+
+```typescript
+import { Client } from "gstatx";
+
+const client = new Client({
+  cloneIfNotExists: true,
+  repositories: [
+    {
+      path: "/path/to/repository",
+    },
+  ],
+  contributors: {
+    "no-commits": false
+  },
+});
+
+// List contributors
+const contributors = await client.listContributors();
+// Returns: Array<{ path: string; contributors: RepoContributor[] }>
+
+// Get commit history
+const history = await client.getHistory(
+  undefined, // use config repositories
+  "1 month ago", // since
+  "now" // until
+);
+// Returns: Array<{ path: string; commits: Commit[] }>
+```
+
+### Available Exports
+
+```typescript
+import {
+  Client,
+  getContributors,
+  getCommits,
+  isGitRepo,
+  ensureRepository,
+  loadConfig,
+  type RepoContributor,
+  type Commit,
+  type GstatxConfig,
+  type RepositoryConfig,
+} from "gstatx";
+```
+
+### Client Options
+
+```typescript
+interface ClientOptions {
+  cloneIfNotExists?: boolean;
+  repositories?: RepositoryConfig[];
+  configPath?: string;
+  contributors?: {
+    "no-commits"?: boolean;
+  };
+}
+```
+
 ## Development
 
 ### Prerequisites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstatx",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Export stats of a repo or list of repos",
   "type": "module",
   "engines": {