gstatx 0.1.0 → 0.1.1

package/README.md

@@ -1,15 +1,205 @@
 # gstatx
 
-To install dependencies:
+📊 Export statistics from git repositories
+
+A CLI tool to analyze and export statistics from one or multiple git repositories.
+
+## Installation
 
 ```bash
-bun install
+npm install -g gstatx
 ```
 
-To run:
+Or using npm:
 
 ```bash
-bun run src/index.ts
+npm install -g gstatx
+```
+
+## Quick Start
+
+```bash
+# List contributors for a repository
+gstatx contributors ./my-repo
+
+# List contributors for multiple repositories
+gstatx contributors ./repo1 ./repo2 ./repo3
+
+# Hide commit counts
+gstatx contributors --no-commits ./my-repo
 ```
 
-This project was created using `bun init` in bun v1.2.14. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## User Guide
+
+### Commands
+
+#### `contributors`
+
+List contributors for specified git repositories.
+
+**Usage:**
+```bash
+gstatx contributors [options] <repo-path> [repo-path2 ...]
+```
+
+**Options:**
+- `--no-commits` - Hide commit counts in contributor list
+- `--help, -h` - Show help message
+
+**Examples:**
+```bash
+# List contributors with commit counts
+gstatx contributors ./my-repo
+
+# List contributors without commit counts
+gstatx contributors --no-commits ./my-repo
+
+# List contributors for multiple repositories
+gstatx contributors ./repo1 ./repo2 ./repo3
+```
+
+### 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.
+
+**Config File Location:**
+- Default: `.gstatxrc.json` (searched from current directory up to root)
+- Custom: Use `--config` or `-c` flag to specify a custom path
+
+**Configuration Options:**
+
+```json
+{
+  "contributors": {
+    "no-commits": false
+  },
+  "cloneIfNotExists": false,
+  "repositories": [
+    {
+      "path": "../my-repo",
+      "name": "My Repository",
+      "url": "git@github.com:user/repo.git"
+    }
+  ]
+}
+```
+
+**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
+  - `path` (string, required): Repository path (relative to config file location)
+  - `name` (string, optional): Display name for the repository
+  - `url` (string, optional): Git URL for cloning (required if `cloneIfNotExists: true`)
+
+**Important Notes:**
+- 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
+
+**Example Config File:**
+
+```json
+{
+  "contributors": {
+    "no-commits": false
+  },
+  "cloneIfNotExists": true,
+  "repositories": [
+    {
+      "path": "../project-a",
+      "name": "Project A",
+      "url": "git@github.com:user/project-a.git"
+    },
+    {
+      "path": "../project-b",
+      "name": "Project B",
+      "url": "git@github.com:user/project-b.git"
+    }
+  ]
+}
+```
+
+### Global Options
+
+- `--help, -h` - Show help message
+- `--config, -c <path>` - Specify custom config file path
+
+**Examples:**
+```bash
+# Use custom config file
+gstatx --config ./custom-config.json contributors
+
+# Short form
+gstatx -c ./custom-config.json contributors
+```
+
+### Using Config File Repositories
+
+If you have repositories defined in your config file, you can run commands without specifying paths:
+
+```bash
+# Uses repositories from .gstatxrc.json
+gstatx contributors
+```
+
+The tool will automatically use the repositories listed in your config file.
+
+### Auto-Cloning Repositories
+
+When `cloneIfNotExists: true` is set in your config:
+
+1. The tool checks if each repository exists at the specified path
+2. If the repository doesn't exist and a `url` is provided, it will be cloned automatically
+3. If the repository already exists, it will be used as-is
+4. If the path exists but isn't a git repository, an error is shown
+
+**Example:**
+```json
+{
+  "cloneIfNotExists": true,
+  "repositories": [
+    {
+      "path": "../new-repo",
+      "name": "New Repository",
+      "url": "git@github.com:user/repo.git"
+    }
+  ]
+}
+```
+
+Running `gstatx contributors` will automatically clone the repository if it doesn't exist.
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- Bun (for development)
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Build the project
+bun run build
+
+# Run locally
+bun run src/index.ts contributors ./my-repo
+```
+
+### Scripts
+
+- `bun run build` - Build the project
+- `bun run start` - Run the CLI locally
+- `bun run check` - Check code quality
+- `bun run check:fix` - Fix code quality issues
+- `bun run lint` - Lint the code
+- `bun run format` - Format the code
+
+## License
+
+MIT

package/dist/commands/contributors.d.ts

@@ -0,0 +1,8 @@
+export interface RepoContributor {
+    name: string;
+    email: string;
+    commits: number;
+}
+export declare function getContributors(repoPath: string): Promise<RepoContributor[]>;
+export declare function showHelp(): void;
+export declare function listContributors(repoPaths: string[], showCommits?: boolean): Promise<void>;

package/dist/index.js

@@ -1,2 +1,14 @@
 #!/usr/bin/env node
-async function c(){let b=process.argv.slice(2);if(b.length===0)console.log("Usage: gstatx <repo-path> [repo-path2 ...]"),console.log("  Export statistics for one or more git repositories"),process.exit(1);console.log("Repositories to analyze:",b)}c().catch(console.error);
+import{exec as S}from"node:child_process";import{promisify as D}from"node:util";import{access as F}from"node:fs/promises";import{join as N}from"node:path";async function Z(q){try{return await F(N(q,".git")),!0}catch{return!1}}var E=D(S);async function v(q){try{let{stdout:Q}=await E("git shortlog -sn --all",{cwd:q}),z=[],K=Q.trim().split(`
+`);for(let B of K){let J=B.match(/^\s*(\d+)\s+(.+)$/);if(J){let U=parseInt(J[1]||"0",10),X=J[2]||"",{stdout:$}=await E(`git log --format='%aE' --author="${X.replace(/"/g,"\\\"")}" -1`,{cwd:q}),M=$.trim().split(`
+`)[0]||"";z.push({name:X,email:M,commits:U})}}return z.sort((B,J)=>J.commits-B.commits)}catch(Q){throw new Error(`Failed to get contributors from ${q}: ${Q}`)}}function L(){console.log("Usage: gstatx contributors [options] <repo-path> [repo-path2 ...]"),console.log(`
+List contributors for specified git repositories.`),console.log(`
+Options:`),console.log("  --no-commits    Hide commit counts in contributor list"),console.log("  --help, -h      Show this help message"),console.log(`
+Examples:`),console.log("  gstatx contributors ./my-repo"),console.log("  gstatx contributors ./repo1 ./repo2 ./repo3"),console.log("  gstatx contributors --no-commits ./my-repo")}async function R(q,Q=!0){for(let z of q){if(!await Z(z)){console.error(`Error: ${z} is not a git repository`);continue}try{let B=await v(z);if(console.log(`
+\uD83D\uDCCA Contributors for ${z}:`),console.log("─".repeat(60)),B.length===0)console.log("  No contributors found");else for(let J of B)if(Q)console.log(`  ${J.name} <${J.email}> (${J.commits} commits)`);else console.log(`  ${J.name} <${J.email}>`)}catch(B){console.error(`Error processing ${z}:`,B)}}}import{existsSync as H}from"node:fs";import{readFile as y}from"node:fs/promises";import{dirname as I,join as b,resolve as k}from"node:path";var x=".gstatxrc.json";function A(q){let Q=k(q),z=20,K=0;while(K<z){let B=b(Q,x);if(H(B))return B;let J=I(Q);if(J===Q)break;Q=J,K++}return null}async function G(q,Q=process.cwd()){try{let z;if(q){let U=k(q);if(!H(U))return console.error(`Error: Config file not found: ${U}`),null;z=U}else if(z=A(Q),!z)return null;let K=await y(z,"utf-8"),B=JSON.parse(K),J=I(z);if(B.repositories)B.repositories=B.repositories.map((U)=>({...U,path:k(J,U.path)}));return{config:B,configDir:J}}catch(z){if(q)console.error(`Error: Failed to load config file: ${z}`);return null}}import{exec as C}from"node:child_process";import{existsSync as O}from"node:fs";import{mkdir as u}from"node:fs/promises";import{dirname as l}from"node:path";import{promisify as f}from"node:util";var P=f(C);async function _(q){if(O(q.path)&&await Z(q.path))return q.path;if(O(q.path))return console.error(`Error: Path exists but is not a git repository: ${q.path}`),null;if(!q.url)return console.error(`Error: Repository not found at ${q.path} and no URL provided for cloning`),null;try{console.log(`Cloning repository from ${q.url} to ${q.path}...`);let Q=l(q.path),z=q.path.split("/").pop()||"repository";try{await u(Q,{recursive:!0})}catch(K){}return await P(`git clone "${q.url}" "${q.path}"`),console.log(`✓ Successfully cloned ${q.name||z}`),q.path}catch(Q){return console.error(`Error: Failed to clone repository: ${Q}`),null}}function j(){console.log("Usage: gstatx [command] [options] <repo-path> [repo-path2 ...]"),console.log(`
+A CLI tool to export statistics from git repositories.`),console.log(`
+Commands:`),console.log("  contributors    List contributors for specified repositories"),console.log(`
+Global Options:`),console.log("  --help, -h           Show help message"),console.log("  --config, -c <path>  Specify custom config file path"),console.log(`
+Configuration:`),console.log("  You can create a .gstatxrc.json file to set default options"),console.log("  and repository paths. CLI arguments override config values."),console.log("  Set 'cloneIfNotExists: true' to automatically clone repositories"),console.log("  that don't exist locally (requires 'url' in repository config)."),console.log(`
+Examples:`),console.log("  gstatx contributors ./my-repo"),console.log("  gstatx contributors --help"),console.log("  gstatx --config ./custom-config.json contributors"),console.log(`
+Run 'gstatx <command> --help' for command-specific help.`)}function d(q){let Q=[],z;for(let K=0;K<q.length;K++){let B=q[K];if(B==="--config"||B==="-c"){let J=q[K+1];if(!J||J.startsWith("-"))console.error(`Error: ${B} requires a config file path`),process.exit(1);z=J,K++}else Q.push(B??"")}return{configPath:z,remainingArgs:Q}}async function m(){let q=process.argv.slice(2);if(q.length===0||q[0]==="--help"||q[0]==="-h")j(),process.exit(0);let{configPath:Q,remainingArgs:z}=d(q),K=z[0],B=z.slice(1);if(!K)console.error("Error: No command or repository paths specified"),process.exit(1);if(B.includes("--help")||B.includes("-h")){if(K==="contributors")L(),process.exit(0);console.error(`Error: Unknown command "${K}"`),j(),process.exit(1)}let J=await G(Q),U=B.includes("--no-commits"),X=J?.config.contributors?.["no-commits"]??!1,$=!(U||X),V=B.filter((W)=>W!=="--no-commits"&&W!=="--help"&&W!=="-h");if(V.length===0&&J?.config.repositories){let W=J.config.repositories;if(J.config.cloneIfNotExists){let Y=[];for(let w of W){let T=await _(w);if(T)Y.push(T)}V=Y}else V=W.map((Y)=>Y.path)}if(V.length===0&&K==="contributors")console.error("Error: No repository paths specified"),console.log("Run 'gstatx contributors --help' for usage information"),console.log("Or configure repositories in .gstatxrc.json"),process.exit(1);switch(K){case"contributors":await R(V,$);break;default:if(K.startsWith("-")||K.includes("/")||K===".")console.log("Repositories to analyze:",[K,...V]);else console.error(`Error: Unknown command "${K}"`),console.log("Run 'gstatx' without arguments to see usage"),process.exit(1)}}m().catch(console.error);

package/dist/lib.d.ts

@@ -0,0 +1,37 @@
+/**
+ * gstatx - Library API
+ * Export stats of a repo or list of repos
+ */
+import { type RepoContributor } from "./commands/contributors.js";
+import type { GstatxConfig, RepositoryConfig } from "./utils/config.js";
+export type * from "./types.js";
+export interface ClientOptions extends GstatxConfig {
+    cloneIfNotExists?: boolean;
+    repositories?: RepositoryConfig[];
+}
+export declare class Client {
+    private config;
+    private loadedConfig;
+    constructor(options: ClientOptions);
+    /**
+     * Initialize the client by loading config file if needed
+     */
+    private initialize;
+    /**
+     * Get repository paths to use
+     */
+    private getRepoPaths;
+    /**
+     * List contributors for specified repositories
+     * @param repoPaths Optional array of repository paths. If not provided, uses repositories from config.
+     * @returns Array of contributors grouped by repository
+     */
+    listContributors(repoPaths?: string[]): Promise<Array<{
+        path: string;
+        contributors: RepoContributor[];
+    }>>;
+}
+export { getContributors } from "./commands/contributors.js";
+export { loadConfig } from "./utils/config.js";
+export { ensureRepository } from "./utils/repo.js";
+export { isGitRepo } from "./utils/git.js";

package/dist/lib.js

@@ -0,0 +1,3 @@
+import{exec as E}from"node:child_process";import{promisify as N}from"node:util";import{access as L}from"node:fs/promises";import{join as O}from"node:path";async function T(q){try{return await L(O(q,".git")),!0}catch{return!1}}var Z=N(E);async function U(q){try{let{stdout:z}=await Z("git shortlog -sn --all",{cwd:q}),B=[],J=z.trim().split(`
+`);for(let K of J){let H=K.match(/^\s*(\d+)\s+(.+)$/);if(H){let Q=parseInt(H[1]||"0",10),Y=H[2]||"",{stdout:M}=await Z(`git log --format='%aE' --author="${Y.replace(/"/g,"\\\"")}" -1`,{cwd:q}),I=M.trim().split(`
+`)[0]||"";B.push({name:Y,email:I,commits:Q})}}return B.sort((K,H)=>H.commits-K.commits)}catch(z){throw new Error(`Failed to get contributors from ${q}: ${z}`)}}import{existsSync as $}from"node:fs";import{readFile as R}from"node:fs/promises";import{dirname as k,join as A,resolve as V}from"node:path";var F=".gstatxrc.json";function _(q){let z=V(q),B=20,J=0;while(J<B){let K=A(z,F);if($(K))return K;let H=k(z);if(H===z)break;z=H,J++}return null}async function W(q,z=process.cwd()){try{let B;if(q){let Q=V(q);if(!$(Q))return console.error(`Error: Config file not found: ${Q}`),null;B=Q}else if(B=_(z),!B)return null;let J=await R(B,"utf-8"),K=JSON.parse(J),H=k(B);if(K.repositories)K.repositories=K.repositories.map((Q)=>({...Q,path:V(H,Q.path)}));return{config:K,configDir:H}}catch(B){if(q)console.error(`Error: Failed to load config file: ${B}`);return null}}import{exec as D}from"node:child_process";import{existsSync as w}from"node:fs";import{mkdir as G}from"node:fs/promises";import{dirname as S}from"node:path";import{promisify as v}from"node:util";var j=v(D);async function X(q){if(w(q.path)&&await T(q.path))return q.path;if(w(q.path))return console.error(`Error: Path exists but is not a git repository: ${q.path}`),null;if(!q.url)return console.error(`Error: Repository not found at ${q.path} and no URL provided for cloning`),null;try{console.log(`Cloning repository from ${q.url} to ${q.path}...`);let z=S(q.path),B=q.path.split("/").pop()||"repository";try{await G(z,{recursive:!0})}catch(J){}return await j(`git clone "${q.url}" "${q.path}"`),console.log(`✓ Successfully cloned ${q.name||B}`),q.path}catch(z){return console.error(`Error: Failed to clone repository: ${z}`),null}}class C{config;loadedConfig=null;constructor(q){this.config=q}async initialize(){if(!this.config.repositories){if(this.loadedConfig=await W(),this.loadedConfig?.config.repositories)this.config.repositories=this.loadedConfig.config.repositories}if(this.config.cloneIfNotExists&&this.config.repositories){let q=[];for(let z of this.config.repositories){let B=await X(z);if(B)q.push(B)}this.config.repositories=this.config.repositories.map((z,B)=>({...z,path:q[B]||z.path}))}}getRepoPaths(q){if(q&&q.length>0)return q;if(this.config.repositories)return this.config.repositories.map((z)=>z.path);return[]}async listContributors(q){await this.initialize();let z=this.getRepoPaths(q);if(z.length===0)throw new Error("No repository paths specified");let B=[];for(let J of z){if(!await T(J))throw new Error(`${J} is not a git repository`);try{let H=await U(J);B.push({path:J,contributors:H})}catch(H){throw new Error(`Failed to get contributors from ${J}: ${H}`)}}return B}}export{W as loadConfig,T as isGitRepo,U as getContributors,X as ensureRepository,C as Client};

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type { RepoContributor } from "./commands/contributors";
+export type { ContributorsConfig, GstatxConfig, LoadedConfig, RepositoryConfig, } from "./utils/config";

package/dist/utils/config.d.ts

@@ -0,0 +1,18 @@
+export interface RepositoryConfig {
+    path: string;
+    name?: string;
+    url?: string;
+}
+export interface ContributorsConfig {
+    "no-commits"?: boolean;
+}
+export interface GstatxConfig {
+    contributors?: ContributorsConfig;
+    repositories?: RepositoryConfig[];
+    cloneIfNotExists?: boolean;
+}
+export interface LoadedConfig {
+    config: GstatxConfig;
+    configDir: string;
+}
+export declare function loadConfig(customPath?: string, startPath?: string): Promise<LoadedConfig | null>;

package/dist/utils/git.d.ts

@@ -0,0 +1 @@
+export declare function isGitRepo(path: string): Promise<boolean>;

package/dist/utils/repo.d.ts

@@ -0,0 +1,2 @@
+import type { RepositoryConfig } from "./config.js";
+export declare function ensureRepository(repo: RepositoryConfig): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstatx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Export stats of a repo or list of repos",
   "type": "module",
   "engines": {
@@ -9,12 +9,20 @@
   "bin": {
     "gstatx": "dist/index.js"
   },
-  "main": "dist/index.js",
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js",
+      "default": "./dist/lib.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --minify",
+    "build": "bun build src/index.ts --outdir dist --target node --minify && bun build src/lib.ts --outdir dist --target node --minify && tsc -p tsconfig.build.json",
     "prepack": "bun run build",
     "start": "bun run src/index.ts",
     "lint": "biome lint .",