ghscope 0.1.0__tar.gz

ghscope-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: ghscope
+Version: 0.1.0
+Summary: Extensive GitHub activity and contribution reporting
+Author-email: Fuad Alizada <f.alizada@alievsspace.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: weasyprint>=62.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: respx>=0.21.1; extra == "dev"
+Requires-Dist: types-python-dateutil>=2.9.0; extra == "dev"
+
+## ghscope
+
+`ghscope` generates auditable activity reports for GitHub organisations and users.
+
+It pulls commits, pull requests, issues and reviews through the GitHub GraphQL API, then aggregates them into human‑readable reports in Markdown, HTML, PDF, JSON and CSV.
+
+The HTML export is a self‑contained dashboard with a sidebar, filters and per‑entity breakdowns; PDFs are generated from the same template for a print‑ready view.
+
+---
+
+### Installation
+
+`ghscope` targets Python 3.12+.
+
+With `uv` (recommended):
+
+```bash
+uv add ghscope
+```
+
+With `pip`:
+
+```bash
+pip install ghscope
+```
+
+---
+
+### Authentication
+
+`ghscope` uses a GitHub fine‑grained personal access token.
+
+The token must have:
+
+- **Repository access** to the repos you want to analyse (ideally “All repositories” for the organisation).
+- **Scopes/permissions** that allow reading:
+  - code
+  - pull requests
+  - issues
+  - organisation members (for org‑wide reports)
+
+You can pass the token explicitly or via environment variables.
+
+Checked in order:
+
+1. `--token` CLI flag
+2. `GH_FINE_GRAINED_TOKEN`
+3. `GITHUB_TOKEN`
+4. `GH_TOKEN`
+
+---
+
+### CLI usage
+
+Once installed, a `ghscope` entrypoint is available on your PATH.
+
+Basic help:
+
+```bash
+ghscope --help
+ghscope report --help
+```
+
+Generate a Markdown report for an organisation over a date range:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format md \
+  --output ./report.md
+```
+
+Generate an HTML dashboard:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format html \
+  --output ./report.html
+```
+
+Generate a JSON export suitable for further processing:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format json \
+  --output ./report.json
+```
+
+Generate a PDF (requires WeasyPrint and its system dependencies):
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format pdf \
+  --output ./report.pdf
+```
+
+You can also run reports for a single user:
+
+```bash
+ghscope report \
+  --user martian56 \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format html \
+  --output ./user-report.html
+```
+
+`--org` and `--user` can be combined; the tool will analyse all repos visible to the token in that scope.
+
+---
+
+### HTML dashboard
+
+The HTML output is a static, portable dashboard with:
+
+- **Overview**: repository count, commit/PR/issue totals, lines changed, active/inactive contributors.
+- **Contributors**: per‑user activity, sorted by total impact.
+- **Repositories**: per‑repo summaries (commits, lines, PRs, issues, distinct contributors).
+- **Activity timeline**: stacked bars per day (commits, PRs, issues).
+- **Pull requests, commits, issues**: detailed tables with titles/messages, authors, counts and state.
+
+There is a small filter bar at the top:
+
+- **Focus on contributor**: pick a user to see only their work; all sections (overview, repos, timeline, PRs, commits, issues) realign to that view.
+- **Filter by text**: search across titles and messages.
+
+The page is fully static: no build step, no external assets, and it can be served from any static host or converted to PDF.
+
+---
+
+### Data exported
+
+Depending on the format, `ghscope` exports:
+
+- **Aggregates**
+  - per‑user counts (commits, lines added/deleted, PRs opened/merged, issues opened/closed/assigned, reviews given/received)
+  - per‑repo counts (commits, lines, PRs, issues, contributor count)
+  - active vs inactive contributors
+  - daily activity buckets
+
+- **Raw entities**
+  - users
+  - repositories
+  - commits
+  - pull requests
+  - issues
+
+The JSON export contains both the aggregates and the raw entities so you can reshape the data as needed.
+
+---
+
+### Notes
+
+- The reports only include repositories and members that the token can see. If you expect more data than appears in a report, check the token’s repo and organisation permissions first.
+- For large organisations, keep an eye on GitHub GraphQL rate limits. `ghscope` logs remaining calls and the reset time when you run with `--verbose`.

ghscope-0.1.0/README.md

@@ -0,0 +1,166 @@
+## ghscope
+
+`ghscope` generates auditable activity reports for GitHub organisations and users.
+
+It pulls commits, pull requests, issues and reviews through the GitHub GraphQL API, then aggregates them into human‑readable reports in Markdown, HTML, PDF, JSON and CSV.
+
+The HTML export is a self‑contained dashboard with a sidebar, filters and per‑entity breakdowns; PDFs are generated from the same template for a print‑ready view.
+
+---
+
+### Installation
+
+`ghscope` targets Python 3.12+.
+
+With `uv` (recommended):
+
+```bash
+uv add ghscope
+```
+
+With `pip`:
+
+```bash
+pip install ghscope
+```
+
+---
+
+### Authentication
+
+`ghscope` uses a GitHub fine‑grained personal access token.
+
+The token must have:
+
+- **Repository access** to the repos you want to analyse (ideally “All repositories” for the organisation).
+- **Scopes/permissions** that allow reading:
+  - code
+  - pull requests
+  - issues
+  - organisation members (for org‑wide reports)
+
+You can pass the token explicitly or via environment variables.
+
+Checked in order:
+
+1. `--token` CLI flag
+2. `GH_FINE_GRAINED_TOKEN`
+3. `GITHUB_TOKEN`
+4. `GH_TOKEN`
+
+---
+
+### CLI usage
+
+Once installed, a `ghscope` entrypoint is available on your PATH.
+
+Basic help:
+
+```bash
+ghscope --help
+ghscope report --help
+```
+
+Generate a Markdown report for an organisation over a date range:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format md \
+  --output ./report.md
+```
+
+Generate an HTML dashboard:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format html \
+  --output ./report.html
+```
+
+Generate a JSON export suitable for further processing:
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format json \
+  --output ./report.json
+```
+
+Generate a PDF (requires WeasyPrint and its system dependencies):
+
+```bash
+ghscope report \
+  --org Alievs-corp \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format pdf \
+  --output ./report.pdf
+```
+
+You can also run reports for a single user:
+
+```bash
+ghscope report \
+  --user martian56 \
+  --since 2026-01-01 \
+  --until 2026-02-28 \
+  --format html \
+  --output ./user-report.html
+```
+
+`--org` and `--user` can be combined; the tool will analyse all repos visible to the token in that scope.
+
+---
+
+### HTML dashboard
+
+The HTML output is a static, portable dashboard with:
+
+- **Overview**: repository count, commit/PR/issue totals, lines changed, active/inactive contributors.
+- **Contributors**: per‑user activity, sorted by total impact.
+- **Repositories**: per‑repo summaries (commits, lines, PRs, issues, distinct contributors).
+- **Activity timeline**: stacked bars per day (commits, PRs, issues).
+- **Pull requests, commits, issues**: detailed tables with titles/messages, authors, counts and state.
+
+There is a small filter bar at the top:
+
+- **Focus on contributor**: pick a user to see only their work; all sections (overview, repos, timeline, PRs, commits, issues) realign to that view.
+- **Filter by text**: search across titles and messages.
+
+The page is fully static: no build step, no external assets, and it can be served from any static host or converted to PDF.
+
+---
+
+### Data exported
+
+Depending on the format, `ghscope` exports:
+
+- **Aggregates**
+  - per‑user counts (commits, lines added/deleted, PRs opened/merged, issues opened/closed/assigned, reviews given/received)
+  - per‑repo counts (commits, lines, PRs, issues, contributor count)
+  - active vs inactive contributors
+  - daily activity buckets
+
+- **Raw entities**
+  - users
+  - repositories
+  - commits
+  - pull requests
+  - issues
+
+The JSON export contains both the aggregates and the raw entities so you can reshape the data as needed.
+
+---
+
+### Notes
+
+- The reports only include repositories and members that the token can see. If you expect more data than appears in a report, check the token’s repo and organisation permissions first.
+- For large organisations, keep an eye on GitHub GraphQL rate limits. `ghscope` logs remaining calls and the reset time when you run with `--verbose`.

ghscope-0.1.0/ghscope/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("ghscope")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

ghscope-0.1.0/ghscope/analytics/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

ghscope-0.1.0/ghscope/analytics/activity.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Iterable
+
+from ghscope.analytics.aggregates import ActivityReport, aggregate_activity
+from ghscope.analytics.timelines import Timelines, build_timelines
+from ghscope.models import Commit, Issue, PullRequest, Repository, User
+
+
+@dataclass
+class AnalyticsResult:
+    activity: ActivityReport
+    timelines: Timelines
+
+
+def compute_analytics(
+    users: Iterable[User],
+    repositories: Iterable[Repository],
+    commits: Iterable[Commit],
+    pull_requests: Iterable[PullRequest],
+    issues: Iterable[Issue],
+    since: datetime,
+    until: datetime,
+) -> AnalyticsResult:
+    activity = aggregate_activity(
+        users=users,
+        repositories=repositories,
+        commits=commits,
+        pull_requests=pull_requests,
+        issues=issues,
+    )
+    timelines = build_timelines(
+        commits=commits,
+        pull_requests=pull_requests,
+        issues=issues,
+    )
+    return AnalyticsResult(activity=activity, timelines=timelines)

ghscope-0.1.0/ghscope/analytics/aggregates.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Mapping, MutableMapping
+
+from ghscope.models import Commit, Issue, PullRequest, Repository, User
+
+
+@dataclass
+class UserActivitySummary:
+    login: str
+    commits: int
+    lines_added: int
+    lines_deleted: int
+    pull_requests_opened: int
+    pull_requests_merged: int
+    issues_opened: int
+    issues_closed: int
+    issues_assigned: int
+    reviews_given: int
+    reviews_received: int
+
+
+@dataclass
+class RepositoryActivitySummary:
+    full_name: str
+    commits: int
+    lines_added: int
+    lines_deleted: int
+    pull_requests_opened: int
+    pull_requests_merged: int
+    issues_opened: int
+    issues_closed: int
+    contributors: int
+
+
+@dataclass
+class ActivityReport:
+    users: Mapping[str, UserActivitySummary]
+    repositories: Mapping[str, RepositoryActivitySummary]
+    active_contributors: List[str]
+    inactive_contributors: List[str]
+
+
+def aggregate_activity(
+    users: Iterable[User],
+    repositories: Iterable[Repository],
+    commits: Iterable[Commit],
+    pull_requests: Iterable[PullRequest],
+    issues: Iterable[Issue],
+    active_threshold: int = 1,
+) -> ActivityReport:
+    """Aggregate per-user and per-repository activity."""
+    user_logins = {user.login for user in users}
+    repo_names = {repo.full_name for repo in repositories}
+
+    user_commits: MutableMapping[str, int] = Counter()
+    user_lines_added: MutableMapping[str, int] = Counter()
+    user_lines_deleted: MutableMapping[str, int] = Counter()
+    repo_commits: MutableMapping[str, int] = Counter()
+    repo_lines_added: MutableMapping[str, int] = Counter()
+    repo_lines_deleted: MutableMapping[str, int] = Counter()
+
+    for commit in commits:
+        login = commit.author_login
+        if login:
+            user_commits[login] += 1
+            user_lines_added[login] += commit.additions
+            user_lines_deleted[login] += commit.deletions
+        repo = commit.repository_full_name
+        repo_commits[repo] += 1
+        repo_lines_added[repo] += commit.additions
+        repo_lines_deleted[repo] += commit.deletions
+
+    user_pr_opened: MutableMapping[str, int] = Counter()
+    user_pr_merged: MutableMapping[str, int] = Counter()
+    user_reviews_given: MutableMapping[str, int] = Counter()
+    user_reviews_received: MutableMapping[str, int] = Counter()
+    repo_pr_opened: MutableMapping[str, int] = Counter()
+    repo_pr_merged: MutableMapping[str, int] = Counter()
+
+    for pr in pull_requests:
+        repo = pr.repository_full_name
+        repo_pr_opened[repo] += 1
+        if pr.is_merged:
+            repo_pr_merged[repo] += 1
+
+        if pr.author_login:
+            user_pr_opened[pr.author_login] += 1
+            if pr.is_merged:
+                user_pr_merged[pr.author_login] += 1
+            user_reviews_received[pr.author_login] += pr.review_count
+
+        for reviewer in pr.reviewer_logins:
+            user_reviews_given[reviewer] += 1
+
+    user_issues_opened: MutableMapping[str, int] = Counter()
+    user_issues_closed: MutableMapping[str, int] = Counter()
+    user_issues_assigned: MutableMapping[str, int] = Counter()
+    repo_issues_opened: MutableMapping[str, int] = Counter()
+    repo_issues_closed: MutableMapping[str, int] = Counter()
+
+    for issue in issues:
+        repo = issue.repository_full_name
+        repo_issues_opened[repo] += 1
+        if issue.closed_at is not None:
+            repo_issues_closed[repo] += 1
+
+        if issue.author_login:
+            user_issues_opened[issue.author_login] += 1
+            if issue.closed_at is not None:
+                user_issues_closed[issue.author_login] += 1
+
+        for assignee in issue.assignee_logins:
+            user_issues_assigned[assignee] += 1
+
+    user_summaries: Dict[str, UserActivitySummary] = {}
+    for login in sorted(user_logins):
+        user_summaries[login] = UserActivitySummary(
+            login=login,
+            commits=user_commits.get(login, 0),
+            lines_added=user_lines_added.get(login, 0),
+            lines_deleted=user_lines_deleted.get(login, 0),
+            pull_requests_opened=user_pr_opened.get(login, 0),
+            pull_requests_merged=user_pr_merged.get(login, 0),
+            issues_opened=user_issues_opened.get(login, 0),
+            issues_closed=user_issues_closed.get(login, 0),
+            issues_assigned=user_issues_assigned.get(login, 0),
+            reviews_given=user_reviews_given.get(login, 0),
+            reviews_received=user_reviews_received.get(login, 0),
+        )
+
+    repo_contributors: MutableMapping[str, set[str]] = defaultdict(set)
+    for commit in commits:
+        if commit.author_login:
+            repo_contributors[commit.repository_full_name].add(commit.author_login)
+    for pr in pull_requests:
+        if pr.author_login:
+            repo_contributors[pr.repository_full_name].add(pr.author_login)
+        for reviewer in pr.reviewer_logins:
+            repo_contributors[pr.repository_full_name].add(reviewer)
+    for issue in issues:
+        if issue.author_login:
+            repo_contributors[issue.repository_full_name].add(issue.author_login)
+        for assignee in issue.assignee_logins:
+            repo_contributors[issue.repository_full_name].add(assignee)
+
+    repo_summaries: Dict[str, RepositoryActivitySummary] = {}
+    for full_name in sorted(repo_names):
+        contributors = repo_contributors.get(full_name, set())
+        repo_summaries[full_name] = RepositoryActivitySummary(
+            full_name=full_name,
+            commits=repo_commits.get(full_name, 0),
+            lines_added=repo_lines_added.get(full_name, 0),
+            lines_deleted=repo_lines_deleted.get(full_name, 0),
+            pull_requests_opened=repo_pr_opened.get(full_name, 0),
+            pull_requests_merged=repo_pr_merged.get(full_name, 0),
+            issues_opened=repo_issues_opened.get(full_name, 0),
+            issues_closed=repo_issues_closed.get(full_name, 0),
+            contributors=len(contributors),
+        )
+
+    contributor_activity: MutableMapping[str, int] = Counter()
+    for summary in user_summaries.values():
+        contributor_activity[summary.login] = (
+            summary.commits
+            + summary.pull_requests_opened
+            + summary.issues_opened
+            + summary.reviews_given
+        )
+
+    active_contributors = sorted(
+        login for login, count in contributor_activity.items() if count >= active_threshold
+    )
+    inactive_contributors = sorted(
+        login for login, count in contributor_activity.items() if count < active_threshold
+    )
+
+    return ActivityReport(
+        users=user_summaries,
+        repositories=repo_summaries,
+        active_contributors=active_contributors,
+        inactive_contributors=inactive_contributors,
+    )

ghscope-0.1.0/ghscope/analytics/timelines.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from datetime import date
+from typing import Iterable, List
+
+from ghscope.models import Commit, Issue, PullRequest
+
+
+@dataclass
+class ActivityBucket:
+    day: date
+    commits: int
+    pull_requests: int
+    issues: int
+
+
+@dataclass
+class Timelines:
+    by_day: List[ActivityBucket]
+
+
+def build_timelines(
+    commits: Iterable[Commit],
+    pull_requests: Iterable[PullRequest],
+    issues: Iterable[Issue],
+) -> Timelines:
+    commit_counts: dict[date, int] = Counter()
+    pr_counts: dict[date, int] = Counter()
+    issue_counts: dict[date, int] = Counter()
+
+    for commit in commits:
+        commit_date = commit.committed_at.date()
+        commit_counts[commit_date] = commit_counts.get(commit_date, 0) + 1
+
+    for pr in pull_requests:
+        pr_date = pr.created_at.date()
+        pr_counts[pr_date] = pr_counts.get(pr_date, 0) + 1
+
+    for issue in issues:
+        issue_date = issue.created_at.date()
+        issue_counts[issue_date] = issue_counts.get(issue_date, 0) + 1
+
+    all_days = sorted(
+        {*(commit_counts.keys()), *(pr_counts.keys()), *(issue_counts.keys())},
+    )
+
+    buckets: List[ActivityBucket] = []
+    for day in all_days:
+        buckets.append(
+            ActivityBucket(
+                day=day,
+                commits=commit_counts.get(day, 0),
+                pull_requests=pr_counts.get(day, 0),
+                issues=issue_counts.get(day, 0),
+            ),
+        )
+
+    return Timelines(by_day=buckets)

ghscope-0.1.0/ghscope/auth/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

ghscope-0.1.0/ghscope/auth/app.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from .token import TokenConfig, resolve_token
+
+
+GITHUB_GRAPHQL_URL = "https://api.github.com/graphql"
+GITHUB_REST_URL = "https://api.github.com"
+
+
+@dataclass(frozen=True)
+class GitHubAuth:
+    """Authentication configuration for GitHub API access."""
+
+    token_config: TokenConfig
+
+    def headers(self) -> Mapping[str, str]:
+        token = resolve_token(self.token_config)
+        return {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }