lupaxa-github-intel 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. lupaxa/github_intel/__init__.py +13 -0
  2. lupaxa/github_intel/__main__.py +8 -0
  3. lupaxa/github_intel/app.py +493 -0
  4. lupaxa/github_intel/checks/__init__.py +1 -0
  5. lupaxa/github_intel/checks/base.py +17 -0
  6. lupaxa/github_intel/checks/releases.py +59 -0
  7. lupaxa/github_intel/checks/workflows.py +34 -0
  8. lupaxa/github_intel/cli.py +699 -0
  9. lupaxa/github_intel/config/__init__.py +1 -0
  10. lupaxa/github_intel/config/defaults.py +150 -0
  11. lupaxa/github_intel/config/editor.py +316 -0
  12. lupaxa/github_intel/config/loader.py +412 -0
  13. lupaxa/github_intel/config/models.py +310 -0
  14. lupaxa/github_intel/config/paths.py +84 -0
  15. lupaxa/github_intel/config/profiles.py +143 -0
  16. lupaxa/github_intel/constants.py +54 -0
  17. lupaxa/github_intel/dates.py +179 -0
  18. lupaxa/github_intel/errors.py +72 -0
  19. lupaxa/github_intel/github/__init__.py +1 -0
  20. lupaxa/github_intel/github/auth.py +40 -0
  21. lupaxa/github_intel/github/client.py +239 -0
  22. lupaxa/github_intel/github/rate_limit.py +107 -0
  23. lupaxa/github_intel/layout.py +141 -0
  24. lupaxa/github_intel/logging_setup.py +51 -0
  25. lupaxa/github_intel/present.py +361 -0
  26. lupaxa/github_intel/reports/__init__.py +1 -0
  27. lupaxa/github_intel/reports/render.py +113 -0
  28. lupaxa/github_intel/storage/__init__.py +1 -0
  29. lupaxa/github_intel/storage/database.py +419 -0
  30. lupaxa/github_intel/sync/__init__.py +1 -0
  31. lupaxa/github_intel/sync/engine.py +671 -0
  32. lupaxa/github_intel/sync/summary.py +308 -0
  33. lupaxa/github_intel/tui/__init__.py +1 -0
  34. lupaxa/github_intel/tui/application.py +487 -0
  35. lupaxa/github_intel/views.py +896 -0
  36. lupaxa_github_intel-0.1.0.dist-info/METADATA +180 -0
  37. lupaxa_github_intel-0.1.0.dist-info/RECORD +41 -0
  38. lupaxa_github_intel-0.1.0.dist-info/WHEEL +5 -0
  39. lupaxa_github_intel-0.1.0.dist-info/entry_points.txt +2 -0
  40. lupaxa_github_intel-0.1.0.dist-info/licenses/LICENCE +21 -0
  41. lupaxa_github_intel-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,13 @@
1
+ """
2
+ GitHub Intel.
3
+
4
+ Python command-line tool for GitHub intelligence.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from .cli import main
10
+
11
+ __all__ = [
12
+ "main",
13
+ ]
@@ -0,0 +1,8 @@
1
+ """Package entry point for ``python -m lupaxa.github_intel``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .cli import main
6
+
7
+ if __name__ == "__main__":
8
+ main()
@@ -0,0 +1,493 @@
1
+ """
2
+ Operations shared by the CLI and the TUI.
3
+
4
+ Neither interface talks to GitHub or SQLite except through this service.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Callable
10
+ import contextlib
11
+ from dataclasses import replace
12
+ from pathlib import Path
13
+ import time
14
+
15
+ import httpx
16
+
17
+ from lupaxa.github_intel.config.defaults import write_default_files
18
+ from lupaxa.github_intel.config.editor import (
19
+ add_repository,
20
+ remove_repository,
21
+ set_repository_fields,
22
+ )
23
+ from lupaxa.github_intel.config.loader import LoadedConfig, load_config
24
+ from lupaxa.github_intel.config.models import RepositorySpec
25
+ from lupaxa.github_intel.config.paths import (
26
+ config_directory,
27
+ data_directory,
28
+ default_config_file,
29
+ )
30
+ from lupaxa.github_intel.config.profiles import (
31
+ ResolvedProfile,
32
+ check_defaults,
33
+ resolve_profile,
34
+ )
35
+ from lupaxa.github_intel.errors import AuthError, ConfigError, NotFound, SyncTooSoon
36
+ from lupaxa.github_intel.github.auth import github_cli_token
37
+ from lupaxa.github_intel.github.client import GitHubClient
38
+ from lupaxa.github_intel.logging_setup import configure_logging
39
+ from lupaxa.github_intel.storage.database import Database, Document
40
+ from lupaxa.github_intel.sync.engine import SyncReport, synchronise
41
+ from lupaxa.github_intel.views import RepositoryView, build_view, select_repositories
42
+
43
+ __all__ = ["Service"]
44
+
45
+ TokenProvider = Callable[[], str | None]
46
+
47
+
48
+ class Service:
49
+ """Load configuration, edit it, read the cache, and synchronise."""
50
+
51
+ def __init__(
52
+ self,
53
+ config_path: Path | None = None,
54
+ data_dir: Path | None = None,
55
+ token_provider: TokenProvider = github_cli_token,
56
+ transport: httpx.AsyncBaseTransport | None = None,
57
+ ) -> None:
58
+ """
59
+ Create a service.
60
+
61
+ Args:
62
+ config_path: Main configuration file, or None for the default.
63
+ data_dir: Cache directory, or None for the XDG data directory.
64
+ token_provider: Supplies the GitHub token. Tests pass a stub.
65
+ transport: Optional HTTP transport. Tests pass a mock.
66
+
67
+ """
68
+
69
+ self.config_path = config_path
70
+ self.data_dir = data_directory() if data_dir is None else data_dir
71
+ self.token_provider = token_provider
72
+ self.transport = transport
73
+ self.log_level: str | None = None
74
+
75
+ def load(self) -> LoadedConfig:
76
+ """
77
+ Load and validate configuration.
78
+
79
+ Returns:
80
+ Loaded configuration.
81
+
82
+ """
83
+
84
+ return load_config(self._require_config())
85
+
86
+ def ensure_config(self) -> Path:
87
+ """
88
+ Return the main configuration path, creating defaults when absent.
89
+
90
+ Returns:
91
+ Path to config.yml. An explicit missing ``--config`` is not created.
92
+
93
+ """
94
+
95
+ if self.config_path is not None:
96
+ return self.config_path
97
+ directory = config_directory()
98
+ current = default_config_file(directory)
99
+ if current.is_file():
100
+ return current
101
+ return write_default_files(directory)
102
+
103
+ async def views(
104
+ self,
105
+ *,
106
+ group: str | None = None,
107
+ profile: str | None = None,
108
+ tag: str | None = None,
109
+ status: str | None = None,
110
+ ) -> list[RepositoryView]:
111
+ """
112
+ List repositories from configuration and the cache.
113
+
114
+ Args:
115
+ group: Group filter.
116
+ profile: Profile filter.
117
+ tag: Tag filter.
118
+ status: Status filter such as ``stale`` or ``disabled``.
119
+
120
+ Returns:
121
+ Display rows.
122
+
123
+ """
124
+
125
+ loaded = self.load()
126
+ database = self._database()
127
+ try:
128
+ rows = []
129
+ for repository in select_repositories(
130
+ loaded,
131
+ group=group,
132
+ profile=profile,
133
+ tag=tag,
134
+ ):
135
+ view = await self._view(loaded, database, repository)
136
+ if status is None or status in view.statuses:
137
+ rows.append(view)
138
+ return rows
139
+ finally:
140
+ await database.close()
141
+
142
+ async def show(
143
+ self,
144
+ repo: str,
145
+ ) -> tuple[RepositoryView, ResolvedProfile, list[Document]]:
146
+ """
147
+ Return one repository, its resolved profile, and cached documents.
148
+
149
+ Args:
150
+ repo: ``owner/name``.
151
+
152
+ Returns:
153
+ View, resolved checks, and documents.
154
+
155
+ Raises:
156
+ NotFound: The repository is not configured.
157
+
158
+ """
159
+
160
+ loaded = self.load()
161
+ repository = _require(loaded, repo)
162
+ database = self._database()
163
+ try:
164
+ view = await self._view(loaded, database, repository)
165
+ documents = await database.documents_for(repository.repo)
166
+ finally:
167
+ await database.close()
168
+ resolved = resolve_profile(
169
+ loaded.profiles,
170
+ repository.profile or loaded.config.defaults.profile,
171
+ repository.checks,
172
+ **check_defaults(loaded.config.defaults),
173
+ )
174
+ return view, resolved, documents
175
+
176
+ async def sync(
177
+ self,
178
+ *,
179
+ force: bool = False,
180
+ group: str | None = None,
181
+ profile: str | None = None,
182
+ repo: str | None = None,
183
+ concurrency: int | None = None,
184
+ on_progress: Callable[[SyncReport], None] | None = None,
185
+ ) -> SyncReport:
186
+ """
187
+ Synchronise enabled repositories.
188
+
189
+ Args:
190
+ force: Ignore cache freshness and ``sync.interval``.
191
+ group: Limit to one group.
192
+ profile: Limit to one profile.
193
+ repo: Limit to one repository.
194
+ concurrency: Override the configured request limit.
195
+ on_progress: Called as counters change. It must not await.
196
+
197
+ Returns:
198
+ Synchronisation statistics.
199
+
200
+ Raises:
201
+ NotFound: ``repo`` is not configured.
202
+ SyncTooSoon: The previous sync is still inside ``sync.interval``.
203
+
204
+ """
205
+
206
+ loaded = self._with_concurrency(self.load(), concurrency)
207
+ if repo is not None:
208
+ _require(loaded, repo)
209
+ matched = select_repositories(loaded, group=group, profile=profile, repo=repo)
210
+ selected = tuple(item for item in matched if item.enabled)
211
+ token = self.token_provider()
212
+ configure_logging(
213
+ self.log_level or loaded.config.logging.level,
214
+ [token] if token else [],
215
+ )
216
+ await self.assert_sync_allowed(force=force)
217
+ database = self._database()
218
+ client = GitHubClient(
219
+ api_url=loaded.config.github.api_url,
220
+ token=token,
221
+ timeout=loaded.config.sync.timeout,
222
+ retries=loaded.config.sync.retries,
223
+ concurrency=loaded.config.sync.concurrency,
224
+ transport=self.transport,
225
+ )
226
+ started = time.time()
227
+ try:
228
+ report = await synchronise(
229
+ loaded,
230
+ database,
231
+ client,
232
+ force=force,
233
+ selected=selected,
234
+ on_progress=on_progress,
235
+ )
236
+ finally:
237
+ await client.aclose()
238
+ report.skipped = len(matched) - len(selected)
239
+ report.elapsed = time.time() - started
240
+ await database.record_run(started, time.time(), _stats(report))
241
+ await database.close()
242
+ return report
243
+
244
+ async def assert_sync_allowed(self, *, force: bool = False) -> None:
245
+ """
246
+ Refuse a sync that starts inside ``sync.interval``.
247
+
248
+ Args:
249
+ force: Skip the interval check.
250
+
251
+ Raises:
252
+ SyncTooSoon: The previous sync is still inside ``sync.interval``.
253
+
254
+ """
255
+
256
+ if force:
257
+ return
258
+ interval = self.load().config.sync.interval
259
+ if interval <= 0:
260
+ return
261
+ database = self._database()
262
+ try:
263
+ await _refuse_if_too_soon(database, interval)
264
+ finally:
265
+ await database.close()
266
+
267
+ async def check_remote(self, repo: str) -> None:
268
+ """
269
+ Confirm GitHub will answer for one repository.
270
+
271
+ Args:
272
+ repo: ``owner/name``.
273
+
274
+ Raises:
275
+ AuthError: GitHub returned 401.
276
+ ConfigError: GitHub returned 404 or another error.
277
+
278
+ """
279
+
280
+ loaded = self.load()
281
+ token = self.token_provider()
282
+ client = GitHubClient(
283
+ api_url=loaded.config.github.api_url,
284
+ token=token,
285
+ timeout=loaded.config.sync.timeout,
286
+ retries=0,
287
+ concurrency=1,
288
+ transport=self.transport,
289
+ )
290
+ try:
291
+ result = await client.get(f"/repos/{repo}")
292
+ finally:
293
+ await client.aclose()
294
+ if result.status == 401:
295
+ raise AuthError(result.error or "GitHub rejected the credentials.")
296
+ if result.error:
297
+ raise ConfigError(result.error)
298
+
299
+ def add(
300
+ self,
301
+ repo: str,
302
+ group: str | None,
303
+ profile: str | None,
304
+ tags: list[str],
305
+ ) -> None:
306
+ """
307
+ Add a repository to the configuration file.
308
+
309
+ Args:
310
+ repo: ``owner/name``.
311
+ group: Optional group.
312
+ profile: Optional profile.
313
+ tags: Tags.
314
+
315
+ """
316
+
317
+ path = self.ensure_config()
318
+ self.config_path = path
319
+ add_repository(path, repo, group=group, profile=profile, tags=tags)
320
+
321
+ def remove(self, repo: str) -> None:
322
+ """
323
+ Remove a repository from configuration.
324
+
325
+ Args:
326
+ repo: ``owner/name``.
327
+
328
+ """
329
+
330
+ remove_repository(self._require_config(), repo)
331
+
332
+ def set_fields(self, repo: str, **fields: bool | str | None) -> None:
333
+ """
334
+ Update fields on a configured repository.
335
+
336
+ Args:
337
+ repo: ``owner/name``.
338
+ fields: Values such as ``enabled`` or ``profile``.
339
+
340
+ """
341
+
342
+ set_repository_fields(self._require_config(), repo, **fields)
343
+
344
+ def reset(self) -> tuple[Path, ...]:
345
+ """
346
+ Delete the cache files.
347
+
348
+ Configuration, profiles, and the repository list stay. The next sync
349
+ starts from an empty cache, including the sync interval.
350
+
351
+ Returns:
352
+ Files that were removed.
353
+
354
+ """
355
+
356
+ database = self._database().path
357
+ names = (
358
+ database,
359
+ Path(f"{database}-wal"),
360
+ Path(f"{database}-shm"),
361
+ Path(f"{database}-journal"),
362
+ )
363
+ removed: list[Path] = []
364
+ for path in names:
365
+ if path.is_file():
366
+ path.unlink()
367
+ removed.append(path)
368
+ with contextlib.suppress(OSError):
369
+ self.data_dir.rmdir()
370
+ return tuple(removed)
371
+
372
+ async def clear_cache(self, repo: str | None) -> None:
373
+ """
374
+ Delete cached rows.
375
+
376
+ Args:
377
+ repo: One repository, or None for the whole cache.
378
+
379
+ """
380
+
381
+ database = self._database()
382
+ try:
383
+ await database.clear(repo)
384
+ finally:
385
+ await database.close()
386
+
387
+ async def vacuum(self) -> None:
388
+ """Rebuild the SQLite file."""
389
+
390
+ database = self._database()
391
+ try:
392
+ await database.vacuum()
393
+ finally:
394
+ await database.close()
395
+
396
+ async def cache_info(self) -> dict[str, int | str]:
397
+ """
398
+ Describe the cache file.
399
+
400
+ Returns:
401
+ Path, size, and row counts.
402
+
403
+ """
404
+
405
+ database = self._database()
406
+ try:
407
+ counts = await database.counts()
408
+ finally:
409
+ await database.close()
410
+ size = database.path.stat().st_size if database.path.exists() else 0
411
+ return {"path": str(database.path), "bytes": size, **counts}
412
+
413
+ def _database(self) -> Database:
414
+ return Database(self.data_dir / "cache.sqlite")
415
+
416
+ def _require_config(self) -> Path:
417
+ if self.config_path is not None:
418
+ if not self.config_path.is_file():
419
+ raise ConfigError(f"{self.config_path} does not exist.")
420
+ return self.config_path
421
+ current = default_config_file(config_directory())
422
+ if not current.is_file():
423
+ raise ConfigError("No configuration file exists.")
424
+ return current
425
+
426
+ async def _view(
427
+ self,
428
+ loaded: LoadedConfig,
429
+ database: Database,
430
+ repository: RepositorySpec,
431
+ ) -> RepositoryView:
432
+ documents = await database.documents_for(repository.repo)
433
+ checks = await database.checks_for(repository.repo)
434
+ return build_view(loaded, repository, documents, checks)
435
+
436
+ def _with_concurrency(
437
+ self,
438
+ loaded: LoadedConfig,
439
+ concurrency: int | None,
440
+ ) -> LoadedConfig:
441
+ if concurrency is None:
442
+ return loaded
443
+ sync = loaded.config.sync.model_copy(update={"concurrency": concurrency})
444
+ config = loaded.config.model_copy(update={"sync": sync})
445
+ return replace(loaded, config=config)
446
+
447
+
448
+ async def _refuse_if_too_soon(database: Database, interval: int) -> None:
449
+ if interval <= 0:
450
+ return
451
+ started = await database.latest_sync_started()
452
+ if started is None:
453
+ return
454
+ elapsed = time.time() - started
455
+ if elapsed >= interval:
456
+ return
457
+ raise SyncTooSoon(
458
+ "Synchronisation is too soon. "
459
+ f"The last sync started {_span(elapsed)} ago.\n"
460
+ f"Wait {_span(interval - elapsed)}, or pass --force. "
461
+ f"sync.interval is {_span(interval)}.",
462
+ )
463
+
464
+
465
+ def _span(seconds: float) -> str:
466
+ total = max(0, int(seconds + 0.5))
467
+ hours, remainder = divmod(total, 3600)
468
+ minutes, secs = divmod(remainder, 60)
469
+ if hours:
470
+ return f"{hours}h {minutes:02d}m {secs:02d}s"
471
+ if minutes:
472
+ return f"{minutes}m {secs:02d}s"
473
+ return f"{secs}s"
474
+
475
+
476
+ def _require(loaded: LoadedConfig, repo: str) -> RepositorySpec:
477
+ for repository in loaded.repositories:
478
+ if repository.repo.casefold() == repo.casefold():
479
+ return repository
480
+ raise NotFound(f"{repo} is not configured.")
481
+
482
+
483
+ def _stats(report: SyncReport) -> dict[str, object]:
484
+ return {
485
+ "repositories": report.repositories,
486
+ "successful": report.successful,
487
+ "failed": report.failed,
488
+ "skipped": report.skipped,
489
+ "requests": report.requests,
490
+ "cache_hits": report.cache_hits,
491
+ "not_modified": report.not_modified,
492
+ "cancelled": report.cancelled,
493
+ }
@@ -0,0 +1 @@
1
+ """Derived repository checks."""
@@ -0,0 +1,17 @@
1
+ """Shared check result."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+ __all__ = ["CheckResult"]
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class CheckResult:
12
+ """One derived check outcome."""
13
+
14
+ name: str
15
+ status: str
16
+ summary: str
17
+ failure: bool = False
@@ -0,0 +1,59 @@
1
+ """Release check evaluation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from lupaxa.github_intel.checks.base import CheckResult
8
+
9
+ __all__ = ["evaluate_releases"]
10
+
11
+
12
+ def evaluate_releases(
13
+ releases: list[dict[str, Any]] | None,
14
+ *,
15
+ compare_status: str | None,
16
+ ahead_by: int | None,
17
+ compare_error: str | None,
18
+ fetch_error: str | None,
19
+ ) -> CheckResult:
20
+ """
21
+ Classify the latest published release against the default branch.
22
+
23
+ Args:
24
+ releases: Release objects from the GitHub API.
25
+ compare_status: Compare API status, when the call succeeded.
26
+ ahead_by: Commits on the default branch after the tag.
27
+ compare_error: Compare call failure, if any.
28
+ fetch_error: Release list failure, if any.
29
+
30
+ Returns:
31
+ Release check result. A tag that is not an ancestor is Unknown.
32
+
33
+ """
34
+
35
+ if fetch_error and not releases:
36
+ return CheckResult("releases", "Error", fetch_error, True)
37
+ published = [item for item in releases or [] if not item.get("draft")]
38
+ if not published:
39
+ return CheckResult("releases", "No releases", "No published releases found.")
40
+ tag = str(published[0].get("tag_name") or "")
41
+ if compare_error:
42
+ return CheckResult("releases", "Unknown", compare_error)
43
+ if compare_status == "diverged":
44
+ return CheckResult(
45
+ "releases",
46
+ "Unknown",
47
+ f"{tag} is not an ancestor of the default branch.",
48
+ )
49
+ if ahead_by is not None and ahead_by > 0:
50
+ return CheckResult(
51
+ "releases",
52
+ f"{ahead_by} Ahead",
53
+ f"{ahead_by} commits ahead on the default branch after {tag}.",
54
+ )
55
+ return CheckResult(
56
+ "releases",
57
+ "Current",
58
+ f"{tag} has no newer commits on the default branch.",
59
+ )
@@ -0,0 +1,34 @@
1
+ """Workflow check evaluation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from lupaxa.github_intel.checks.base import CheckResult
8
+
9
+ __all__ = ["evaluate_workflows"]
10
+
11
+
12
+ def evaluate_workflows(
13
+ workflows: list[dict[str, Any]] | None,
14
+ error: str | None,
15
+ ) -> CheckResult:
16
+ """
17
+ Summarise the workflow list.
18
+
19
+ Args:
20
+ workflows: Workflow name and activity pairs already prepared for display.
21
+ error: Request failure, if any.
22
+
23
+ Returns:
24
+ Workflow check result. Listing workflows is not a failure.
25
+
26
+ """
27
+
28
+ if error:
29
+ return CheckResult("workflows", "Error", error, True)
30
+ count = 0 if workflows is None else len(workflows)
31
+ if count == 0:
32
+ return CheckResult("workflows", "No workflows", "No workflows are configured.")
33
+ noun = "workflow" if count == 1 else "workflows"
34
+ return CheckResult("workflows", "Listed", f"{count} {noun}.")