gitlogstats 1.0.9__tar.gz → 1.2.0__tar.gz

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/.claude/CLAUDE.md

@@ -70,7 +70,8 @@ Changes are tracked on the GitHub project board (https://github.com/users/bloomb
 - **Do not commit code changes directly to the default branch (`master`).** Create a feature branch named `feat/<REQ-ID>-<slug>` (e.g. `feat/STAT-6-mailmap`; use a short descriptive slug when no requirement id applies). **Exception:** documentation (Markdown and anything under `docs/`) and project tooling under `scripts/` and `.claude/` may be committed directly to the default branch without a PR.
 - **Open a pull request** whose description includes `Closes #N` — `N` is the board issue's number — so the issue closes on merge. Commit and push only when asked, and run the checks above first.
 - **Do not hand-create board issues.** The board is generated from the SPEC: `npm run board:derive` regenerates `scripts/board/manifest.yaml`, then `npm run board:sync` creates or updates the issues (`-- --dry-run` previews; `-- --reconcile` forces SPEC statuses back onto the board). A requirement marked `Done` in the SPEC is always closed and moved to Done; other status moves are left to the board unless `--reconcile` is passed.
-- Pushing to `master` publishes a release to PyPI (see `.github/workflows/build.yaml`), so bump `version` in `pyproject.toml` when a change to the package should be released.
+- **Claude runs both board commands itself** (they are pre-approved in `.claude/settings.json`): `board:derive` whenever `docs/SPEC.md` changes, committing the manifest with the change; `board:sync` **before** opening a PR when the SPEC adds requirements (so `Closes #N` has an issue to point at), and again **after** the PR merges. Sync reads the working tree, so before the merge run it from a tree where the new requirements are still `Todo`/`In Progress` — syncing a branch that already marks them `Done` closes their issues before the code lands.
+- Merging a pull request into `master` publishes a release to PyPI once the tests pass on the merged code (see `.github/workflows/build.yaml`); pushes to other branches, and direct pushes to `master`, publish nothing. Bump `version` in `pyproject.toml` in the PR when a change to the package should be released; a merge without a bump skips the upload.
 
 If asked to use a different workflow (e.g. commit code straight to the default branch), **remind the user that it diverges from this flow and confirm before proceeding** — then honor the confirmed request.
 

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/.claude/settings.json

@@ -1,4 +1,7 @@
 {
+  "permissions": {
+    "allow": ["Bash(npm run board:derive*)", "Bash(npm run board:sync*)"]
+  },
   "hooks": {
     "PreToolUse": [
       {

gitlogstats-1.2.0/.github/workflows/build.yaml

@@ -0,0 +1,65 @@
+name: CI / CD
+# CI runs on every pull request into master and on every push to master.
+# Delivery to PyPI happens only when a pull request is merged into master,
+# and only if the tests pass on the merged code (PKG-2, PKG-4).
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+    types: [opened, synchronize, reopened, closed]
+permissions:
+  contents: read
+jobs:
+  build:
+    # a pull request closed without merging needs no checks
+    if: github.event.action != 'closed' || github.event.pull_request.merged
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.11']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # after a merge, test the merge commit that landed on master
+          ref: ${{ github.event.pull_request.merged && github.event.pull_request.merge_commit_sha || github.sha }}
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --user pipenv
+          pipenv --python python install --dev --skip-lock
+      - name: Run tests
+        run: |
+          pipenv run python -m pytest -q
+      - name: Build package
+        run: |
+          pipenv run python -m build .
+  deliver:
+    # only a merged pull request is released, and only after build passed
+    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build .
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # a merge without a version bump (e.g. tooling only) skips the upload
+          skip-existing: true

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitlogstats
-Version: 1.0.9
+Version: 1.2.0
 Summary: Track developers' contributions to one or more git repositories within a particular time range.
 Project-URL: Homepage, https://github.com/bloombar/gitlogstats
 Project-URL: Repository, https://github.com/bloombar/gitlogstats.git
@@ -709,6 +709,8 @@ This script calculates the following, for each developer in each repository:
 - number of **files changed**
 - number of **merges** into the analyzed branch
 
+With `--github`, it also reports each developer's GitHub **pull requests** opened, merged, closed without merging and merged by themselves (see [GitHub pull requests](#github-pull-requests)).
+
 The results can be formatted as `csv`, `json`, or `markdown`.
 
 ## Install
@@ -722,26 +724,37 @@ e.g. `pip install gitlogstats`, `pip3 install gitlogstats`, depending on your en
 The command `gitlogstats --help` shows the usage instructions:
 
 ```
-usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START] [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}] [-b BRANCH] [-v] [-c]
+usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START]
+                   [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}]
+                   [-b BRANCH] [-v] [-c] [--github]
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -r REPOSITORY, --repository REPOSITORY
                         the public URL of the repository whose logs to parse
   -rf REPOFILE, --repofile REPOFILE
-                        the path to simple text file with a list of repository URLs to parse
-  -u USER, --user USER  The git username (or email address) to report. Default is all contributing users
+                        the path to simple text file with a list of repository
+                        URLs to parse
+  -u USER, --user USER  The git username (or email address) to report. Default
+                        is all contributing users
   -s START, --start START
                         Start date in mm/dd/yyyy format
   -e END, --end END     End date in mm/dd/yyyy format
   -x EXCLUSIONS, --exclusions EXCLUSIONS
-                        A comma-separated list of files, patterns or directories to exclude, e.g. --exclusions "foo.zip, *.jpg, vendor". Replaces the default list; use "" to exclude nothing
+                        A comma-separated list of files, patterns or
+                        directories to exclude, e.g. --exclusions "foo.zip,
+                        *.jpg, vendor". Replaces the default list; use "" to
+                        exclude nothing
   -f {csv,json,markdown}, --format {csv,json,markdown}
                         The format in which to output the results
   -b BRANCH, --branch BRANCH
-                        The branch to checkout before compiling statistics. Defaults to the repository's default branch.
+                        The branch to parse, if not the default branch
   -v, --verbose         Whether to output debugging info
   -c, --clean           Remove contributors without any contribuition
+  --github              Also report GitHub pull requests opened, merged,
+                        closed and self-merged per contributor, and match
+                        GitHub users to git authors. Needs the GitHub CLI
+                        (gh), signed in
 ```
 
 In case `gitlogstats` is not found as a command, even after installing, try `python -m gitlogstats` or `python3 -m gitlogstats` instead.
@@ -822,6 +835,47 @@ By default, every contributor in a repository's history is listed, with zeros fo
 gitlogstats -rf repos.txt -c
 ```
 
+### GitHub pull requests
+
+Add `--github` to also count each contributor's pull requests. Five columns are appended to every output format:
+
+| Column                | Meaning                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `github_username`     | the GitHub account matched to the contributor (never the display name), so you can check the matching   |
+| `prs_opened`          | pull requests they opened in the date range, whatever their state now (drafts included)                 |
+| `prs_merged`          | pull requests they authored that were merged in the date range, by anyone and in any way (squash too)   |
+| `prs_closed_unmerged` | pull requests they authored that were closed without merging in the date range                          |
+| `prs_self_merged`     | pull requests they authored and also merged themselves, merged in the date range (also in `prs_merged`) |
+
+```
+gitlogstats -r https://github.com/bloombar/gitlogstats.git --github
+```
+
+**Requirements.** Only `--github` needs the [GitHub CLI](https://cli.github.com) (`gh`); without the flag nothing changes and GitHub is never contacted. Install `gh`, then run `gh auth login`. The tool checks this before cloning anything. If it fails, nothing is printed to standard output, the exit status is 1 and one of these messages is printed to standard error:
+
+```
+gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.
+gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.
+```
+
+**Empty versus zero.** A zero means GitHub was asked and the person has none. An empty value (`null` in JSON) means GitHub could not be asked for that repository: it is not on github.com, or the request failed (no network, rate limit, a private repository you cannot see). The git statistics are still reported, the reason is printed to standard error, and the other repositories carry on. A contributor with no GitHub account matched has an empty `github_username` and zero pull requests. A GitHub user who opened pull requests but has no commits is listed in a row of their own with an empty `username` and zero git statistics.
+
+**Matching GitHub users to git authors.** Each git author name is compared with the GitHub users active in the repository, trying these in order and stopping at the first that finds exactly one user:
+
+1. **Email.** The email is a GitHub `noreply` address containing the username, GitHub itself links one of the author's commits to an account, or the email is the public email of a GitHub profile.
+2. **Username.** The author name, or the part of the email before the `@`, is the GitHub username (ignoring case, and treating spaces, hyphens, underscores and dots as alike). The part before the `@` is skipped when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when several author names in the repository share it (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name is the GitHub profile name (ignoring case, accents, punctuation and word order, so `Grace Hopper` matches `Hopper, Grace`).
+
+If a step finds several users it is skipped as ambiguous and the next is tried. All git names matched to one GitHub user become one row: the `username` is the name with the most commits and the git statistics are added up. Use `-v` to see which step matched each name, the ambiguous and unmatched names, and how many `gh` calls were made. A wrong match can be fixed with a `.mailmap` file.
+
+**How the other options apply.**
+
+- `-s` / `-e`: each pull request count uses its own timestamp (opened, merged or closed) against the same inclusive local-time range as commits.
+- `-b`: only pull requests whose base branch is that branch are counted; without `-b`, all pull requests count.
+- `-u`: selects the combined row whose author names or emails equal the value exactly, or whose GitHub username equals it ignoring case. The whole combined row is reported, so `-u` with one email address also includes the person's commits under their other names and emails, and a value that matches nobody prints no row.
+- `-c`: removes only rows with no git activity and no pull requests.
+- `-x`: has no effect on pull requests.
+
 ### Formatting the results
 
 The results can be formatted as `csv`, `json`, or a `markdown` table. The default is `csv`. Use the `-f` flag to control the output format.

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/Pipfile

@@ -5,8 +5,6 @@ name = "pypi"
 
 [packages]
 gitlogstats = {editable = true, path = "."}
-pytest = "*"
-build = "*"
 
 [dev-packages]
 build = "*"

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "70462452caf90504e4b0e1fa21f9c94c9ab312ca80771fa5d2d656e939a719aa"
+            "sha256": "d1fee7a304fa34eaf74ad0dd93b88859d18b03c32476298928a490a03ec616e8"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -16,67 +16,9 @@
         ]
     },
     "default": {
-        "build": {
-            "hashes": [
-                "sha256:51cc11666391ab6f092070437ac747002ff46f3e4113a3622177ee6b488bfc53",
-                "sha256:ecd351a4be9d35a9eaaba244a7687143c9c7d4aea6ac964e7e7ddab20cbcf4e7"
-            ],
-            "index": "pypi",
-            "markers": "python_version >= '3.10'",
-            "version": "==1.6.1"
-        },
         "gitlogstats": {
             "editable": true,
             "path": "."
-        },
-        "iniconfig": {
-            "hashes": [
-                "sha256:67f4b9c50da0dedf52af349e7749a80a9057a5031199791b906c3bb3ae878960",
-                "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7"
-            ],
-            "markers": "python_version >= '3.10'",
-            "version": "==2.3.1"
-        },
-        "packaging": {
-            "hashes": [
-                "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79",
-                "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c"
-            ],
-            "markers": "python_version >= '3.9'",
-            "version": "==26.3"
-        },
-        "pluggy": {
-            "hashes": [
-                "sha256:7dd7b0d8832ba3cb632c306926ded123429211b83641b35dc5c41ad2d34f9bec",
-                "sha256:d1eaa46ebb595891b860ab086b4d09c8588af65ebd4361b8e8f4bb8920b90ba8"
-            ],
-            "markers": "python_version >= '3.10'",
-            "version": "==1.7.0"
-        },
-        "pygments": {
-            "hashes": [
-                "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9",
-                "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c"
-            ],
-            "markers": "python_version >= '3.9'",
-            "version": "==2.21.0"
-        },
-        "pyproject-hooks": {
-            "hashes": [
-                "sha256:5fc53fdac9f7bd63fbcdc868fb5f90b4784d78a53a3d3388cd738b807441a20b",
-                "sha256:defda19b854fa0d3bd4f76ea4ddcba8abd7dcfcdd585a6690ade050744fc5f43"
-            ],
-            "markers": "python_version >= '3.8'",
-            "version": "==1.3.3"
-        },
-        "pytest": {
-            "hashes": [
-                "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313",
-                "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c"
-            ],
-            "index": "pypi",
-            "markers": "python_version >= '3.10'",
-            "version": "==9.1.1"
         }
     },
     "develop": {

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/README.md

@@ -12,6 +12,8 @@ This script calculates the following, for each developer in each repository:
 - number of **files changed**
 - number of **merges** into the analyzed branch
 
+With `--github`, it also reports each developer's GitHub **pull requests** opened, merged, closed without merging and merged by themselves (see [GitHub pull requests](#github-pull-requests)).
+
 The results can be formatted as `csv`, `json`, or `markdown`.
 
 ## Install
@@ -25,26 +27,37 @@ e.g. `pip install gitlogstats`, `pip3 install gitlogstats`, depending on your en
 The command `gitlogstats --help` shows the usage instructions:
 
 ```
-usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START] [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}] [-b BRANCH] [-v] [-c]
+usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START]
+                   [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}]
+                   [-b BRANCH] [-v] [-c] [--github]
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -r REPOSITORY, --repository REPOSITORY
                         the public URL of the repository whose logs to parse
   -rf REPOFILE, --repofile REPOFILE
-                        the path to simple text file with a list of repository URLs to parse
-  -u USER, --user USER  The git username (or email address) to report. Default is all contributing users
+                        the path to simple text file with a list of repository
+                        URLs to parse
+  -u USER, --user USER  The git username (or email address) to report. Default
+                        is all contributing users
   -s START, --start START
                         Start date in mm/dd/yyyy format
   -e END, --end END     End date in mm/dd/yyyy format
   -x EXCLUSIONS, --exclusions EXCLUSIONS
-                        A comma-separated list of files, patterns or directories to exclude, e.g. --exclusions "foo.zip, *.jpg, vendor". Replaces the default list; use "" to exclude nothing
+                        A comma-separated list of files, patterns or
+                        directories to exclude, e.g. --exclusions "foo.zip,
+                        *.jpg, vendor". Replaces the default list; use "" to
+                        exclude nothing
   -f {csv,json,markdown}, --format {csv,json,markdown}
                         The format in which to output the results
   -b BRANCH, --branch BRANCH
-                        The branch to checkout before compiling statistics. Defaults to the repository's default branch.
+                        The branch to parse, if not the default branch
   -v, --verbose         Whether to output debugging info
   -c, --clean           Remove contributors without any contribuition
+  --github              Also report GitHub pull requests opened, merged,
+                        closed and self-merged per contributor, and match
+                        GitHub users to git authors. Needs the GitHub CLI
+                        (gh), signed in
 ```
 
 In case `gitlogstats` is not found as a command, even after installing, try `python -m gitlogstats` or `python3 -m gitlogstats` instead.
@@ -125,6 +138,47 @@ By default, every contributor in a repository's history is listed, with zeros fo
 gitlogstats -rf repos.txt -c
 ```
 
+### GitHub pull requests
+
+Add `--github` to also count each contributor's pull requests. Five columns are appended to every output format:
+
+| Column                | Meaning                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `github_username`     | the GitHub account matched to the contributor (never the display name), so you can check the matching   |
+| `prs_opened`          | pull requests they opened in the date range, whatever their state now (drafts included)                 |
+| `prs_merged`          | pull requests they authored that were merged in the date range, by anyone and in any way (squash too)   |
+| `prs_closed_unmerged` | pull requests they authored that were closed without merging in the date range                          |
+| `prs_self_merged`     | pull requests they authored and also merged themselves, merged in the date range (also in `prs_merged`) |
+
+```
+gitlogstats -r https://github.com/bloombar/gitlogstats.git --github
+```
+
+**Requirements.** Only `--github` needs the [GitHub CLI](https://cli.github.com) (`gh`); without the flag nothing changes and GitHub is never contacted. Install `gh`, then run `gh auth login`. The tool checks this before cloning anything. If it fails, nothing is printed to standard output, the exit status is 1 and one of these messages is printed to standard error:
+
+```
+gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.
+gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.
+```
+
+**Empty versus zero.** A zero means GitHub was asked and the person has none. An empty value (`null` in JSON) means GitHub could not be asked for that repository: it is not on github.com, or the request failed (no network, rate limit, a private repository you cannot see). The git statistics are still reported, the reason is printed to standard error, and the other repositories carry on. A contributor with no GitHub account matched has an empty `github_username` and zero pull requests. A GitHub user who opened pull requests but has no commits is listed in a row of their own with an empty `username` and zero git statistics.
+
+**Matching GitHub users to git authors.** Each git author name is compared with the GitHub users active in the repository, trying these in order and stopping at the first that finds exactly one user:
+
+1. **Email.** The email is a GitHub `noreply` address containing the username, GitHub itself links one of the author's commits to an account, or the email is the public email of a GitHub profile.
+2. **Username.** The author name, or the part of the email before the `@`, is the GitHub username (ignoring case, and treating spaces, hyphens, underscores and dots as alike). The part before the `@` is skipped when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when several author names in the repository share it (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name is the GitHub profile name (ignoring case, accents, punctuation and word order, so `Grace Hopper` matches `Hopper, Grace`).
+
+If a step finds several users it is skipped as ambiguous and the next is tried. All git names matched to one GitHub user become one row: the `username` is the name with the most commits and the git statistics are added up. Use `-v` to see which step matched each name, the ambiguous and unmatched names, and how many `gh` calls were made. A wrong match can be fixed with a `.mailmap` file.
+
+**How the other options apply.**
+
+- `-s` / `-e`: each pull request count uses its own timestamp (opened, merged or closed) against the same inclusive local-time range as commits.
+- `-b`: only pull requests whose base branch is that branch are counted; without `-b`, all pull requests count.
+- `-u`: selects the combined row whose author names or emails equal the value exactly, or whose GitHub username equals it ignoring case. The whole combined row is reported, so `-u` with one email address also includes the person's commits under their other names and emails, and a value that matches nobody prints no row.
+- `-c`: removes only rows with no git activity and no pull requests.
+- `-x`: has no effect on pull requests.
+
 ### Formatting the results
 
 The results can be formatted as `csv`, `json`, or a `markdown` table. The default is `csv`. Use the `-f` flag to control the output format.

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/docs/SPEC.md

@@ -35,7 +35,7 @@ Repositories are cloned into a `repos/` directory under the current working dire
 
 #### REPO-4 Branch selection
 
-`-b/--branch <name>` checks out the given branch before statistics are computed. Without `-b`, the repository's default branch is used — including when an earlier run left the cached clone on another branch.
+`-b/--branch <name>` checks out the given branch before statistics are computed. Without `-b`, the repository's default branch is used — including when an earlier run left the cached clone on another branch. With `--github`, it also limits which pull requests are counted to those whose base branch is that branch (CLI-3).
 
 **Status:** Done
 
@@ -83,17 +83,54 @@ For each contributor, the number of merge commits they authored directly on the
 
 **Status:** Done
 
+#### STAT-8 Pull requests opened
+
+With `--github` (CLI-3), for each contributor, the number of pull requests they authored on GitHub whose creation time (`created_at`) falls in the date range, whatever their state now (open, merged or closed; drafts included). Reported in a `prs_opened` column.
+
+**Status:** Done
+
+#### STAT-9 Pull requests merged
+
+With `--github`, for each contributor, the number of pull requests they authored that were merged (`merged_at` set) in the date range, whoever merged them. Reported in a `prs_merged` column. Unlike merges (STAT-7), this counts squash and rebase merges too, since GitHub records them as merged pull requests.
+
+**Status:** Done
+
+#### STAT-10 Pull requests closed without merging
+
+With `--github`, for each contributor, the number of pull requests they authored that were closed without being merged (`state` closed and `merged_at` not set), with a closing time (`closed_at`) in the date range. Reported in a `prs_closed_unmerged` column.
+
+**Status:** Done
+
+#### STAT-11 Matching GitHub users to git authors
+
+With `--github`, each pull-request author (a GitHub username) is matched to the git identities (author name and email) in the repository's history. Each git identity is tried against the GitHub users active in that repository (pull-request authors and the accounts GitHub links to its commits), tier by tier, stopping at the first tier that finds exactly one GitHub user:
+
+1. **Email.** The email is a GitHub `noreply` address (`12345+login@users.noreply.github.com` or `login@users.noreply.github.com`); or GitHub links one of the identity's commits to an account (the commit's `author.login`, which covers private emails GitHub knows but does not publish); or the email equals a candidate's public profile email (case-insensitive).
+2. **Username.** The author name, or the email's local part (before `@`), equals a candidate's GitHub username, ignoring case and treating spaces, hyphens, underscores and dots as the same (`Ada Lovelace` matches `Ada-Lovelace`). An email local part is not used when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when it is shared by several author names in the repository (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name equals a candidate's GitHub display name, ignoring case, accents, repeated spaces and punctuation, and word order (`Grace Hopper` matches `Hopper, Grace`).
+4. **No match.** A GitHub user matched by no git identity is reported in a row of its own, with an empty `username`, its pull-request statistics and zero git statistics.
+
+If a tier finds several GitHub users for one identity, that tier is skipped as ambiguous and the next is tried; ambiguous and unmatched identities are listed with `-v`. All git identities matched to the same GitHub user are combined into one row: the `username` is the matched author name with the most commits (ties broken alphabetically), and the git statistics are summed. A git identity matched to no GitHub user keeps its own row with an empty `github_username` and zero pull-request statistics. Every row carries the matched GitHub username (never the display name) in a `github_username` column, so matches can be checked and corrected by hand, e.g. with a `.mailmap` (STAT-6).
+
+**Status:** Done
+
+#### STAT-12 Self-merged pull requests
+
+With `--github`, for each contributor, the number of pull requests they authored and also merged themselves (the GitHub user who merged the pull request is its author, ignoring case), with a merge time (`merged_at`) in the date range. Reported in a `prs_self_merged` column, appended after `prs_closed_unmerged`. Every self-merged pull request is also counted in `prs_merged` (STAT-9), so `prs_self_merged` is never larger than `prs_merged`. A merged pull request whose merger GitHub does not report (e.g. a deleted account) is not counted as self-merged. `-b` and `-s/-e` apply as for `prs_merged`.
+
+**Status:** Done
+
 ### 3. Filtering
 
 #### FILT-1 Date range
 
-`-s/--start` and `-e/--end` (format `mm/dd/yyyy`) limit the analysis to commits whose commit date falls between the start of the start date and the end of the end date, inclusive, in local time. Defaults: one year ago until today. The output records the requested start and end dates on every row.
+`-s/--start` and `-e/--end` (format `mm/dd/yyyy`) limit the analysis to commits whose commit date falls between the start of the start date and the end of the end date, inclusive, in local time. Defaults: one year ago until today. The output records the requested start and end dates on every row. With `--github`, each pull request count is filtered by its own timestamp in the same range (CLI-3).
 
 **Status:** Done
 
 #### FILT-2 Single contributor
 
-`-u/--user <name>` reports only the contributor whose author name or email address matches exactly. Without `-u`, every contributor in the repository's history is reported.
+`-u/--user <name>` reports only the contributor whose author name or email address matches exactly. Without `-u`, every contributor in the repository's history is reported. With `--github`, it selects the combined row, and a value may also be the GitHub username (ignoring case); see CLI-3.
 
 **Status:** Done
 
@@ -105,7 +142,7 @@ For each contributor, the number of merge commits they authored directly on the
 
 #### FILT-4 Remove inactive contributors
 
-By default, contributors with no activity in the date range are listed with zeros. `-c/--clean` removes them.
+By default, contributors with no activity in the date range are listed with zeros. `-c/--clean` removes them. With `--github`, only rows with neither git nor pull-request activity are removed (CLI-3).
 
 **Status:** Done
 
@@ -113,7 +150,7 @@ By default, contributors with no activity in the date range are listed with zero
 
 #### OUT-1 CSV output
 
-`-f csv` (the default) prints a header row followed by one row per contributor per repository, with fields `username, repository, start_date, end_date, commits, insertions, deletions, files, merges`. New fields are added at the end so existing column positions do not change. Values containing commas, quotes or line breaks are quoted. The header is printed even when there are no rows, and the output ends with a single newline.
+`-f csv` (the default) prints a header row followed by one row per contributor per repository, with fields `username, repository, start_date, end_date, commits, insertions, deletions, files, merges`. New fields are added at the end so existing column positions do not change. Values containing commas, quotes or line breaks are quoted. The header is printed even when there are no rows, and the output ends with a single newline. With `--github`, the columns `github_username, prs_opened, prs_merged, prs_closed_unmerged, prs_self_merged` are appended, and are in the header even when there are no rows (CLI-3).
 
 **Status:** Done
 
@@ -137,7 +174,7 @@ When several repositories are analyzed, the results are printed once, after all
 
 #### OUT-5 Verbose diagnostics
 
-`-v/--verbose` prints debugging information (directories, the git commands run, contributors found) to standard error, so standard output stays machine-readable.
+`-v/--verbose` prints debugging information (directories, the git commands run, contributors found) to standard error, so standard output stays machine-readable. With `--github`, it also prints how each author name was matched to a GitHub user, the ambiguous and unmatched names, and the number of `gh` API calls made for each repository (CLI-3).
 
 **Status:** Done
 
@@ -155,6 +192,17 @@ Invalid dates, and a start date after the end date, are rejected with a usage er
 
 **Status:** Done
 
+#### CLI-3 GitHub pull-request statistics
+
+`--github` adds GitHub pull-request statistics (STAT-8 to STAT-12) for repositories hosted on github.com, appending the columns `github_username, prs_opened, prs_merged, prs_closed_unmerged, prs_self_merged` to every output format. Without `--github`, the output and behaviour are unchanged, GitHub is never contacted and the GitHub CLI (`gh`) is not needed. With `--github`, the GitHub API is called through `gh api`, so `gh` must be installed and signed in. This is checked before any repository is cloned; if it fails, nothing is printed to standard output, the tool exits with status 1, and one plain message on standard error says why and what to do — no stack trace:
+
+- `gh` not found: `gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.`
+- `gh` not signed in (`gh auth status` fails): `gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.`
+
+The other options apply to pull requests as follows: `-s/-e` filter each count by its own timestamp, using the same inclusive local-time range as FILT-1; `-u` selects the combined row whose author names, emails or GitHub username match exactly (the username ignoring case); `-b` counts only pull requests whose base branch is that branch, and without `-b` every pull request counts; `-c` removes only rows with neither git nor pull-request activity; `-x` does not apply. For a repository not on github.com, or when GitHub cannot be reached for one repository (no network, rate limit, private repository without access), the git statistics are still reported, the five GitHub columns are empty (`null` in JSON) rather than zero, and the reason is printed to standard error.
+
+**Status:** Done
+
 ### 6. Packaging & Quality
 
 #### PKG-1 Installable package
@@ -165,7 +213,7 @@ The tool installs with `pip install gitlogstats`, which provides a `gitlogstats`
 
 #### PKG-2 Continuous integration and release
 
-GitHub Actions builds the package on every push, on Python 3.9 and 3.11, and publishes it to PyPI.
+GitHub Actions builds the package on Python 3.9 and 3.11 for every pull request into `master` and every push to `master`. It publishes to PyPI only when a pull request is merged into `master` and the build of the merged code passes; pushes to other branches publish nothing. A merge whose version is already on PyPI (no version bump) skips the upload instead of failing.
 
 **Status:** Done
 
@@ -177,9 +225,9 @@ Unit tests cover parsing and formatting, and integration tests build real git re
 
 #### PKG-4 Run tests in CI
 
-The CI workflow runs the test suite on every push and stops the release if any test fails. (Today it builds and publishes without running tests.)
+The CI workflow runs the Python test suite (`pytest`) on every pull request into `master` and every push to `master`, and on the merged code before a release; a failing test stops the release.
 
-**Status:** Todo
+**Status:** Done
 
 ### 7. Future Work
 
@@ -189,3 +237,7 @@ The CI workflow runs the test suite on every push and stops the release if any t
 - **Parallel processing** — clone and analyze many repositories concurrently to speed up large batches.
 - **Per-file breakdown** — optionally report each contributor's changes per file or directory.
 - **Output to file** — write results to a file (e.g. `-o report.csv`) instead of only standard output.
+- **GitHub without the gh CLI** — let `--github` call the GitHub API directly with a `GITHUB_TOKEN`, for users who cannot install `gh`.
+- **GitHub Enterprise hosts** — extend `--github` to repositories on GitHub Enterprise Server, via `gh api --hostname` or a configurable API URL.
+- **Pull-request reviews and mergers** — report who reviewed and who merged each pull request, in addition to who opened it.
+- **GitHub-only mode** — report pull-request statistics without computing git statistics, for faster runs over large batches.

{gitlogstats-1.0.9 → gitlogstats-1.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "gitlogstats"
 description = "Track developers' contributions to one or more git repositories within a particular time range."
-version = "1.0.9"
+version = "1.2.0"
 authors = [
   { name="Tobody Tothing", email="nobody.nothing@nowhere.com" },
 ]