gitsumm 1.0.0__tar.gz

gitsumm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kshitiz Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitsumm-1.0.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: gitsumm
+Version: 1.0.0
+Summary: Get some insight from your git history — plain-English summaries, hotspots, coupling, and more.
+Author: Kshitiz Yadav
+Maintainer: Kshitiz Yadav
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kshitizyadav6/gitsumm
+Project-URL: Repository, https://github.com/kshitizyadav6/gitsumm
+Project-URL: Issues, https://github.com/kshitizyadav6/gitsumm/issues
+Project-URL: Changelog, https://github.com/kshitizyadav6/gitsumm/blob/main/CHANGELOG.md
+Keywords: git,summary,standup,changelog,cli,developer-tools,code-review,insights
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.25; extra == "ai"
+Dynamic: license-file
+
+# gitsumm
+
+*Say it out loud: "get some."* Point it at a repo and get some insight from your
+git history, in plain English.
+
+`git log` tells you *what* happened, one line at a time. `gitsumm` tells you the
+*story*: how many commits, by whom, when activity peaked, whether momentum is up
+or down, and which files only one person has touched (a bus-factor risk). It's
+the digest you paste straight into a standup, changelog, or team update.
+
+## Install
+
+```bash
+pip install -e .          # core tool (works fully offline)
+pip install -e ".[ai]"    # add the optional Anthropic-powered summary
+```
+
+Requires Python 3.8+. The only hard dependencies are `typer` and `rich`; the
+`anthropic` SDK is an optional extra used only by `--ai`.
+
+## Usage
+
+```bash
+gitsumm                 # summarize the last 7 days
+gitsumm --days 14       # custom window (alias: -d 14)
+gitsumm --standup       # commit subjects grouped by author
+gitsumm --hotspots 5    # rank the top N churn hotspots (high-risk files)
+gitsumm --coupling      # files that tend to change together (hidden coupling)
+gitsumm --verbose       # extra detail, incl. the lowest-hygiene commits (-v)
+gitsumm --ai            # add a fluent paragraph via the Anthropic SDK
+gitsumm --changelog     # themed changelog (Features / Fixes / Refactors / Other)
+gitsumm since v1.0.0    # summarize everything since a tag (or between two tags)
+gitsumm since v1.0.0 --changelog   # release notes for a range
+gitsumm --version
+gitsumm --help
+```
+
+### Default summary
+
+```
+╭──────────────── gitsumm · myrepo · get some ───────────────╮
+│ Got some — 24 commits from 3 contributors in the last 7 days │
+│ Most active: Alice (14 commits)                              │
+│ Busiest day: Tuesday (9 commits)                             │
+│ Files touched: 18                                            │
+│ Commit hygiene: 86/100                                       │
+│ Hottest file: payments.py — 23 changes, 5 authors. Handle with care. │
+│ Momentum: ↑ up 6 vs previous 7 days (18 → 24)                │
+│ Heads up — 30% of commits land outside working hours...      │
+│                                                              │
+│ Bus-factor risk — 3 files touched by a single author:        │
+│   • auth.py — only Alice                                     │
+│   • billing.py — only Bob                                    │
+│   • reports.py — only Alice                                  │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+The **momentum**, **bus-factor**, and **hottest-file** lines are the point of
+the tool — insights a raw log won't give you. Momentum compares this window
+against the equal-length window immediately before it. Bus-factor flags files
+only one author has touched in the window, busiest first, so knowledge silos
+surface. The inline "Hottest file" line names the single highest-risk file (only
+when there's real churn). A "Heads up" line flags **work-hours patterns** —
+appearing only when a meaningful share of commits land outside working hours
+(before 8am / after 8pm) or on weekends, so it reads as a team-health signal
+rather than noise. A **commit hygiene** score (0–100) rates workflow health — it
+penalizes one-word or vague messages and oversized commits; `--verbose` lists
+the worst offenders.
+
+### Churn hotspots — where the heat is
+
+High-churn, multi-author files are where defects concentrate. `--hotspots N`
+ranks them in a dedicated panel, scored as `changes × distinct authors`:
+
+```
+╭──── hotspots · myrepo · where the heat is ────╮
+│   • payments.py — 23 changes · 5 authors · score 115 │
+│   • auth.py — 12 changes · 3 authors · score 36      │
+│   • api.py — 9 changes · 2 authors · score 18        │
+╰────────────────────────────────────────────────╯
+```
+
+### Co-change coupling — the usual suspects
+
+Files that almost always commit together are coupled whether the code says so or
+not — surfacing undocumented dependencies. `--coupling` reports pairs that
+co-occur often enough (and with a high enough ratio) to matter; bulk commits
+touching many files are ignored so they don't manufacture false coupling.
+
+```
+╭──── usual suspects · myrepo · files that travel together ────╮
+│   • auth.py ↔ session.py — change together 90% of the time (9×) │
+│   • api.py ↔ schema.py — change together 80% of the time (8×)   │
+╰────────────────────────────────────────────────────────────────╯
+```
+
+### Standup mode
+
+```
+╭─ gitsumm · myrepo · get some standup (in the last 7 days) ─╮
+│ Alice (3 commits)                                         │
+│   • Add weekly report export                              │
+│   • Hash passwords with bcrypt                            │
+│   • Add login endpoint                                    │
+│                                                           │
+│ Bob (1 commit)                                            │
+│   • Fix invoice rounding                                  │
+╰───────────────────────────────────────────────────────────╯
+```
+
+### AI mode
+
+With the `[ai]` extra installed and `ANTHROPIC_API_KEY` set, `--ai` adds a
+fluent paragraph above the stats panel:
+
+```
+╭───────────────── gitsumm · myrepo · the gist ─────────────────╮
+│ Over the past week myrepo saw steady progress: 24 commits    │
+│ from three contributors, with Alice driving most of the auth  │
+│ work and Tuesday the busiest day. Momentum is up on the prior │
+│ week. Heads up — auth.py and reports.py have only been        │
+│ touched by Alice, a bus-factor risk worth spreading around.   │
+╰───────────────────────────────────────────────────────────────╯
+```
+
+`--ai` never breaks the tool: if the `anthropic` SDK isn't installed, the API
+key is missing, or the request fails, gitsumm falls back to a deterministic
+templated paragraph and prints a short hint explaining why. Set
+`GITSUMM_AI_MODEL` to use a model other than the default.
+
+### Themed changelog & tag ranges
+
+`--changelog` groups commits into **Features / Fixes / Refactors / Other** —
+fluent release notes when AI is available, a deterministic keyword grouping
+when it isn't (same crash-proof fallback as `--ai`). Pair it with the `since`
+command to summarize a release instead of a day window:
+
+```
+gitsumm since v1.0.0 --changelog          # everything since a tag
+gitsumm since v1.0.0 v1.1.0 --changelog   # between two tags
+```
+
+```
+╭─ gitsumm · myrepo · changelog (since v1.0.0) ─╮
+│ Features                                     │
+│   • Add user login endpoint                  │
+│   • Add billing webhook                      │
+│ Fixes                                        │
+│   • Fix invoice rounding                     │
+│ Refactors                                    │
+│   • Refactor reports module                  │
+╰──────────────────────────────────────────────╯
+```
+
+Every flag above (`--standup`, `--hotspots`, `--coupling`, `--ai`, `--verbose`)
+also works with `since`.
+
+## Behavior & guarantees
+
+- **Works fully offline.** AI is an enhancement, never a requirement.
+- **Fails friendly.** Not a git repo, no commits in the window, or git not
+  installed each produce a clear one-line message and a clean exit — never a
+  stack trace.
+- **Reads `ANTHROPIC_API_KEY`** from the environment; missing key during `--ai`
+  falls back gracefully.
+
+## Project layout
+
+```
+gitsumm/
+├── main.py        # CLI wiring + output formatting (typer + rich)
+├── git_utils.py   # all git/subprocess logic and analysis; returns clean objects
+└── ai.py          # optional Anthropic summary, fully isolated and crash-proof
+```

gitsumm-1.0.0/README.md

@@ -0,0 +1,174 @@
+# gitsumm
+
+*Say it out loud: "get some."* Point it at a repo and get some insight from your
+git history, in plain English.
+
+`git log` tells you *what* happened, one line at a time. `gitsumm` tells you the
+*story*: how many commits, by whom, when activity peaked, whether momentum is up
+or down, and which files only one person has touched (a bus-factor risk). It's
+the digest you paste straight into a standup, changelog, or team update.
+
+## Install
+
+```bash
+pip install -e .          # core tool (works fully offline)
+pip install -e ".[ai]"    # add the optional Anthropic-powered summary
+```
+
+Requires Python 3.8+. The only hard dependencies are `typer` and `rich`; the
+`anthropic` SDK is an optional extra used only by `--ai`.
+
+## Usage
+
+```bash
+gitsumm                 # summarize the last 7 days
+gitsumm --days 14       # custom window (alias: -d 14)
+gitsumm --standup       # commit subjects grouped by author
+gitsumm --hotspots 5    # rank the top N churn hotspots (high-risk files)
+gitsumm --coupling      # files that tend to change together (hidden coupling)
+gitsumm --verbose       # extra detail, incl. the lowest-hygiene commits (-v)
+gitsumm --ai            # add a fluent paragraph via the Anthropic SDK
+gitsumm --changelog     # themed changelog (Features / Fixes / Refactors / Other)
+gitsumm since v1.0.0    # summarize everything since a tag (or between two tags)
+gitsumm since v1.0.0 --changelog   # release notes for a range
+gitsumm --version
+gitsumm --help
+```
+
+### Default summary
+
+```
+╭──────────────── gitsumm · myrepo · get some ───────────────╮
+│ Got some — 24 commits from 3 contributors in the last 7 days │
+│ Most active: Alice (14 commits)                              │
+│ Busiest day: Tuesday (9 commits)                             │
+│ Files touched: 18                                            │
+│ Commit hygiene: 86/100                                       │
+│ Hottest file: payments.py — 23 changes, 5 authors. Handle with care. │
+│ Momentum: ↑ up 6 vs previous 7 days (18 → 24)                │
+│ Heads up — 30% of commits land outside working hours...      │
+│                                                              │
+│ Bus-factor risk — 3 files touched by a single author:        │
+│   • auth.py — only Alice                                     │
+│   • billing.py — only Bob                                    │
+│   • reports.py — only Alice                                  │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+The **momentum**, **bus-factor**, and **hottest-file** lines are the point of
+the tool — insights a raw log won't give you. Momentum compares this window
+against the equal-length window immediately before it. Bus-factor flags files
+only one author has touched in the window, busiest first, so knowledge silos
+surface. The inline "Hottest file" line names the single highest-risk file (only
+when there's real churn). A "Heads up" line flags **work-hours patterns** —
+appearing only when a meaningful share of commits land outside working hours
+(before 8am / after 8pm) or on weekends, so it reads as a team-health signal
+rather than noise. A **commit hygiene** score (0–100) rates workflow health — it
+penalizes one-word or vague messages and oversized commits; `--verbose` lists
+the worst offenders.
+
+### Churn hotspots — where the heat is
+
+High-churn, multi-author files are where defects concentrate. `--hotspots N`
+ranks them in a dedicated panel, scored as `changes × distinct authors`:
+
+```
+╭──── hotspots · myrepo · where the heat is ────╮
+│   • payments.py — 23 changes · 5 authors · score 115 │
+│   • auth.py — 12 changes · 3 authors · score 36      │
+│   • api.py — 9 changes · 2 authors · score 18        │
+╰────────────────────────────────────────────────╯
+```
+
+### Co-change coupling — the usual suspects
+
+Files that almost always commit together are coupled whether the code says so or
+not — surfacing undocumented dependencies. `--coupling` reports pairs that
+co-occur often enough (and with a high enough ratio) to matter; bulk commits
+touching many files are ignored so they don't manufacture false coupling.
+
+```
+╭──── usual suspects · myrepo · files that travel together ────╮
+│   • auth.py ↔ session.py — change together 90% of the time (9×) │
+│   • api.py ↔ schema.py — change together 80% of the time (8×)   │
+╰────────────────────────────────────────────────────────────────╯
+```
+
+### Standup mode
+
+```
+╭─ gitsumm · myrepo · get some standup (in the last 7 days) ─╮
+│ Alice (3 commits)                                         │
+│   • Add weekly report export                              │
+│   • Hash passwords with bcrypt                            │
+│   • Add login endpoint                                    │
+│                                                           │
+│ Bob (1 commit)                                            │
+│   • Fix invoice rounding                                  │
+╰───────────────────────────────────────────────────────────╯
+```
+
+### AI mode
+
+With the `[ai]` extra installed and `ANTHROPIC_API_KEY` set, `--ai` adds a
+fluent paragraph above the stats panel:
+
+```
+╭───────────────── gitsumm · myrepo · the gist ─────────────────╮
+│ Over the past week myrepo saw steady progress: 24 commits    │
+│ from three contributors, with Alice driving most of the auth  │
+│ work and Tuesday the busiest day. Momentum is up on the prior │
+│ week. Heads up — auth.py and reports.py have only been        │
+│ touched by Alice, a bus-factor risk worth spreading around.   │
+╰───────────────────────────────────────────────────────────────╯
+```
+
+`--ai` never breaks the tool: if the `anthropic` SDK isn't installed, the API
+key is missing, or the request fails, gitsumm falls back to a deterministic
+templated paragraph and prints a short hint explaining why. Set
+`GITSUMM_AI_MODEL` to use a model other than the default.
+
+### Themed changelog & tag ranges
+
+`--changelog` groups commits into **Features / Fixes / Refactors / Other** —
+fluent release notes when AI is available, a deterministic keyword grouping
+when it isn't (same crash-proof fallback as `--ai`). Pair it with the `since`
+command to summarize a release instead of a day window:
+
+```
+gitsumm since v1.0.0 --changelog          # everything since a tag
+gitsumm since v1.0.0 v1.1.0 --changelog   # between two tags
+```
+
+```
+╭─ gitsumm · myrepo · changelog (since v1.0.0) ─╮
+│ Features                                     │
+│   • Add user login endpoint                  │
+│   • Add billing webhook                      │
+│ Fixes                                        │
+│   • Fix invoice rounding                     │
+│ Refactors                                    │
+│   • Refactor reports module                  │
+╰──────────────────────────────────────────────╯
+```
+
+Every flag above (`--standup`, `--hotspots`, `--coupling`, `--ai`, `--verbose`)
+also works with `since`.
+
+## Behavior & guarantees
+
+- **Works fully offline.** AI is an enhancement, never a requirement.
+- **Fails friendly.** Not a git repo, no commits in the window, or git not
+  installed each produce a clear one-line message and a clean exit — never a
+  stack trace.
+- **Reads `ANTHROPIC_API_KEY`** from the environment; missing key during `--ai`
+  falls back gracefully.
+
+## Project layout
+
+```
+gitsumm/
+├── main.py        # CLI wiring + output formatting (typer + rich)
+├── git_utils.py   # all git/subprocess logic and analysis; returns clean objects
+└── ai.py          # optional Anthropic summary, fully isolated and crash-proof
+```

gitsumm-1.0.0/gitsumm/__init__.py

@@ -0,0 +1,3 @@
+"""gitsumm — summarize a git repository's recent activity in plain English."""
+
+__version__ = "1.0.0"