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,310 @@
1
+ """
2
+ Configuration models.
3
+
4
+ Missing optional values receive defaults. Unknown keys and invalid types
5
+ are rejected instead of being replaced.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+
12
+ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
13
+
14
+ from lupaxa.github_intel.constants import CHECK_NAMES, DEFAULT_PROFILE, UNGROUPED
15
+ from lupaxa.github_intel.dates import DEFAULT_DATE_FORMAT, require_date_format
16
+ from lupaxa.github_intel.layout import parse_labels
17
+
18
+ __all__ = [
19
+ "AppConfig",
20
+ "CacheSettings",
21
+ "DefaultsSettings",
22
+ "DisplaySettings",
23
+ "FileSettings",
24
+ "GitHubSettings",
25
+ "LoggingSettings",
26
+ "ProfileSpec",
27
+ "RepositorySpec",
28
+ "SyncSettings",
29
+ "ViewSettings",
30
+ ]
31
+
32
+ _VIEW_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
33
+
34
+ _LOG_LEVELS = {"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"}
35
+
36
+
37
+ class _StrictModel(BaseModel):
38
+ model_config = ConfigDict(extra="forbid")
39
+
40
+
41
+ class GitHubSettings(_StrictModel):
42
+ """GitHub API location. Credentials are never read from this file."""
43
+
44
+ api_url: str = "https://api.github.com"
45
+
46
+ @field_validator("api_url")
47
+ @classmethod
48
+ def _api_url(cls, value: str) -> str:
49
+ text = value.strip().rstrip("/")
50
+ if not text.startswith("https://"):
51
+ message = "github.api_url must be an https URL."
52
+ raise ValueError(message)
53
+ return text
54
+
55
+
56
+ class FileSettings(_StrictModel):
57
+ """Paths of the profile and repository files, relative to config.yml."""
58
+
59
+ profiles: str = "profiles.yml"
60
+ repositories: str = "repositories.yml"
61
+
62
+
63
+ class CacheSettings(_StrictModel):
64
+ """Per-category freshness windows, in seconds."""
65
+
66
+ enabled: bool = True
67
+ metadata_ttl: int = Field(default=3600, ge=0)
68
+ releases_ttl: int = Field(default=1800, ge=0)
69
+ workflows_ttl: int = Field(default=900, ge=0)
70
+ issues_ttl: int = Field(default=1800, ge=0)
71
+
72
+
73
+ class SyncSettings(_StrictModel):
74
+ """Bounded synchronisation settings."""
75
+
76
+ concurrency: int = Field(default=10, ge=1)
77
+ timeout: float = Field(default=15, gt=0)
78
+ retries: int = Field(default=3, ge=0)
79
+ interval: int = Field(default=0, ge=0)
80
+ cache: CacheSettings = Field(default_factory=CacheSettings)
81
+
82
+
83
+ class LoggingSettings(_StrictModel):
84
+ """Logging level stored in configuration."""
85
+
86
+ level: str = "INFO"
87
+
88
+ @field_validator("level")
89
+ @classmethod
90
+ def _level(cls, value: str) -> str:
91
+ text = value.strip().upper()
92
+ if text not in _LOG_LEVELS:
93
+ message = "logging.level must be CRITICAL, ERROR, WARNING, INFO, or DEBUG."
94
+ raise ValueError(message)
95
+ return text
96
+
97
+
98
+ class ProfileSpec(_StrictModel):
99
+ """One monitoring profile. Omitted checks are inherited or taken from defaults."""
100
+
101
+ extends: str | None = None
102
+ releases: bool | None = None
103
+ workflows: bool | None = None
104
+ issues: bool | None = None
105
+ pull_requests: bool | None = None
106
+ quality: bool | None = None
107
+
108
+
109
+ class RepositorySpec(_StrictModel):
110
+ """One configured repository."""
111
+
112
+ repo: str
113
+ group: str = UNGROUPED
114
+ profile: str | None = None
115
+ tags: list[str] = Field(default_factory=list)
116
+ enabled: bool = True
117
+ checks: dict[str, bool] = Field(default_factory=dict)
118
+
119
+ @field_validator("repo")
120
+ @classmethod
121
+ def _repo(cls, value: str) -> str:
122
+ return _repository_name(value)
123
+
124
+ @field_validator("group")
125
+ @classmethod
126
+ def _group(cls, value: str) -> str:
127
+ text = value.strip()
128
+ if text == "":
129
+ message = "group must not be blank."
130
+ raise ValueError(message)
131
+ return text
132
+
133
+ @field_validator("tags")
134
+ @classmethod
135
+ def _tags(cls, value: list[str]) -> list[str]:
136
+ cleaned: list[str] = []
137
+ for tag in value:
138
+ text = tag.strip()
139
+ if text == "":
140
+ message = "tags must not contain a blank value."
141
+ raise ValueError(message)
142
+ cleaned.append(text)
143
+ return cleaned
144
+
145
+ @field_validator("checks")
146
+ @classmethod
147
+ def _checks(cls, value: dict[str, bool]) -> dict[str, bool]:
148
+ unknown = sorted(set(value) - set(CHECK_NAMES))
149
+ if unknown:
150
+ message = f"Unknown check names: {', '.join(unknown)}."
151
+ raise ValueError(message)
152
+ return value
153
+
154
+
155
+ class DefaultsSettings(_StrictModel):
156
+ """Default profile name and the check flags used when no profile sets them."""
157
+
158
+ profile: str = DEFAULT_PROFILE
159
+ releases: bool = False
160
+ workflows: bool = False
161
+ issues: bool = False
162
+ pull_requests: bool = True
163
+ quality: bool = True
164
+
165
+ @field_validator("profile")
166
+ @classmethod
167
+ def _profile(cls, value: str) -> str:
168
+ text = value.strip()
169
+ if text == "":
170
+ message = "defaults.profile must not be blank."
171
+ raise ValueError(message)
172
+ return text
173
+
174
+
175
+ class ViewSettings(_StrictModel):
176
+ """One named list and/or detail layout."""
177
+
178
+ list: tuple[str, ...] | None = None
179
+ detail: tuple[str, ...] | None = None
180
+
181
+ @field_validator("list", mode="before")
182
+ @classmethod
183
+ def _list(cls, value: object) -> tuple[str, ...] | None:
184
+ if value is None:
185
+ return None
186
+ if not isinstance(value, (list, tuple)):
187
+ message = "list must be a list of field names."
188
+ raise ValueError(message)
189
+ labels: list[str] = []
190
+ for item in value:
191
+ if not isinstance(item, str):
192
+ message = "list must be a list of field names."
193
+ raise ValueError(message)
194
+ labels.append(item)
195
+ return parse_labels(labels)
196
+
197
+ @field_validator("detail", mode="before")
198
+ @classmethod
199
+ def _detail(cls, value: object) -> tuple[str, ...] | None:
200
+ if value is None:
201
+ return None
202
+ if not isinstance(value, (list, tuple)):
203
+ message = "detail must be a list of field names."
204
+ raise ValueError(message)
205
+ labels: list[str] = []
206
+ for item in value:
207
+ if not isinstance(item, str):
208
+ message = "detail must be a list of field names."
209
+ raise ValueError(message)
210
+ labels.append(item)
211
+ return parse_labels(labels)
212
+
213
+ @model_validator(mode="after")
214
+ def _requires_a_side(self) -> ViewSettings:
215
+ if self.list is None and self.detail is None:
216
+ message = "a view must define list and/or detail."
217
+ raise ValueError(message)
218
+ return self
219
+
220
+
221
+ class DisplaySettings(_StrictModel):
222
+ """
223
+ How dates are shown, which view is selected, and the named views.
224
+
225
+ Attributes:
226
+ date_format: Pattern for dates in tables and reports.
227
+ view: Name of the selected view. ``default`` is always valid.
228
+ views: Named views, each with an optional list and detail.
229
+
230
+ """
231
+
232
+ date_format: str = DEFAULT_DATE_FORMAT
233
+ view: str = "default"
234
+ views: dict[str, ViewSettings] = Field(default_factory=dict)
235
+
236
+ @field_validator("date_format")
237
+ @classmethod
238
+ def _date_format(cls, value: str) -> str:
239
+ return require_date_format(value)
240
+
241
+ @field_validator("view")
242
+ @classmethod
243
+ def _view(cls, value: str) -> str:
244
+ return value.strip()
245
+
246
+ @field_validator("views")
247
+ @classmethod
248
+ def _views(cls, value: dict[str, ViewSettings]) -> dict[str, ViewSettings]:
249
+ rebuilt: dict[str, ViewSettings] = {}
250
+ for name, entry in value.items():
251
+ text = name.strip()
252
+ if not _VIEW_NAME.match(text):
253
+ message = f"invalid view name {name!r}."
254
+ raise ValueError(message)
255
+ if text in rebuilt:
256
+ message = f"duplicate view name {text!r}."
257
+ raise ValueError(message)
258
+ rebuilt[text] = entry
259
+ return rebuilt
260
+
261
+ @model_validator(mode="after")
262
+ def _active_view(self) -> DisplaySettings:
263
+ if self.view != "default" and self.view not in self.views:
264
+ message = f"unknown display view {self.view!r}."
265
+ raise ValueError(message)
266
+ return self
267
+
268
+
269
+ class AppConfig(_StrictModel):
270
+ """The main ``config.yml`` document."""
271
+
272
+ version: int
273
+ github: GitHubSettings = Field(default_factory=GitHubSettings)
274
+ files: FileSettings = Field(default_factory=FileSettings)
275
+ defaults: DefaultsSettings = Field(default_factory=DefaultsSettings)
276
+ display: DisplaySettings = Field(default_factory=DisplaySettings)
277
+ sync: SyncSettings = Field(default_factory=SyncSettings)
278
+ logging: LoggingSettings = Field(default_factory=LoggingSettings)
279
+
280
+ @field_validator("version")
281
+ @classmethod
282
+ def _version(cls, value: int) -> int:
283
+ if value != 1:
284
+ message = "version must be 1."
285
+ raise ValueError(message)
286
+ return value
287
+
288
+
289
+ def _repository_name(value: str) -> str:
290
+ text = value.strip()
291
+ owner, separator, name = text.partition("/")
292
+ invalid = (
293
+ separator != "/"
294
+ or "/" in name
295
+ or owner in {"", ".", ".."}
296
+ or name in {"", ".", ".."}
297
+ or any(character.isspace() for character in text)
298
+ )
299
+ if invalid or not _segment(owner) or not _segment(name):
300
+ message = "repo must be owner/name."
301
+ raise ValueError(message)
302
+ if name.casefold().endswith(".git"):
303
+ message = "repo must not end with .git."
304
+ raise ValueError(message)
305
+ return f"{owner}/{name}"
306
+
307
+
308
+ def _segment(value: str) -> bool:
309
+ allowed = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-")
310
+ return all(character in allowed for character in value)
@@ -0,0 +1,84 @@
1
+ """
2
+ Resolve configuration and cache directories.
3
+
4
+ macOS and Linux use the XDG paths (``~/.config`` and ``~/.local/share``).
5
+ Windows uses platformdirs.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ from pathlib import Path
12
+ import sys
13
+
14
+ from platformdirs import PlatformDirs
15
+ from platformdirs.unix import Unix
16
+
17
+ __all__ = [
18
+ "config_directory",
19
+ "data_directory",
20
+ "default_config_file",
21
+ ]
22
+
23
+
24
+ def config_directory() -> Path:
25
+ """
26
+ Return the directory that holds config.yml.
27
+
28
+ ``GITHUB_INTEL_CONFIG_DIR`` overrides the platform default.
29
+
30
+ Returns:
31
+ Configuration directory. The directory is not created.
32
+
33
+ """
34
+
35
+ return _configured_directory("GITHUB_INTEL_CONFIG_DIR", "user_config_dir")
36
+
37
+
38
+ def data_directory() -> Path:
39
+ """
40
+ Return the directory that holds the SQLite cache.
41
+
42
+ ``GITHUB_INTEL_DATA_DIR`` overrides the platform default.
43
+
44
+ Returns:
45
+ Data directory. The directory is not created.
46
+
47
+ """
48
+
49
+ return _configured_directory("GITHUB_INTEL_DATA_DIR", "user_data_dir")
50
+
51
+
52
+ def default_config_file(directory: Path | None = None) -> Path:
53
+ """
54
+ Return the main configuration file inside ``directory``.
55
+
56
+ An existing ``config.yml``, ``config.yaml``, or ``config.json`` wins.
57
+ Otherwise the path is ``config.yml`` even when that file is absent.
58
+
59
+ Args:
60
+ directory: Configuration directory. Defaults to :func:`config_directory`.
61
+
62
+ Returns:
63
+ Path to the main configuration file.
64
+
65
+ """
66
+
67
+ root = config_directory() if directory is None else directory
68
+ for name in ("config.yml", "config.yaml", "config.json"):
69
+ candidate = root / name
70
+ if candidate.is_file():
71
+ return candidate
72
+ return root / "config.yml"
73
+
74
+
75
+ def _configured_directory(env_name: str, attribute: str) -> Path:
76
+ override = os.environ.get(env_name)
77
+ if override is not None and override.strip() != "":
78
+ return Path(override).expanduser()
79
+ dirs: PlatformDirs | Unix
80
+ if sys.platform == "win32":
81
+ dirs = PlatformDirs(appname="github-intel", appauthor=False)
82
+ else:
83
+ dirs = Unix(appname="github-intel", appauthor=False)
84
+ return Path(getattr(dirs, attribute))
@@ -0,0 +1,143 @@
1
+ """
2
+ Single-parent profile inheritance.
3
+
4
+ Resolution does not depend on the order of profiles in the file.
5
+ An explicit false overrides an inherited true.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass
11
+
12
+ from lupaxa.github_intel.config.models import DefaultsSettings, ProfileSpec
13
+ from lupaxa.github_intel.constants import CHECK_NAMES
14
+ from lupaxa.github_intel.errors import ConfigError
15
+
16
+ __all__ = [
17
+ "ResolvedProfile",
18
+ "check_defaults",
19
+ "resolve_profile",
20
+ ]
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class ResolvedProfile:
25
+ """Effective check flags and the profile that set each one."""
26
+
27
+ name: str
28
+ chain: tuple[str, ...]
29
+ enabled: dict[str, bool]
30
+ sources: dict[str, str]
31
+
32
+
33
+ def check_defaults(settings: DefaultsSettings) -> dict[str, bool]:
34
+ """
35
+ Return the check flags from configuration.
36
+
37
+ Args:
38
+ settings: The ``defaults`` block.
39
+
40
+ Returns:
41
+ One value per check. A profile overrides these when it sets the flag.
42
+
43
+ """
44
+
45
+ return {
46
+ "releases": settings.releases,
47
+ "workflows": settings.workflows,
48
+ "issues": settings.issues,
49
+ "pull_requests": settings.pull_requests,
50
+ "quality": settings.quality,
51
+ }
52
+
53
+
54
+ def resolve_profile(
55
+ profiles: dict[str, ProfileSpec],
56
+ name: str,
57
+ overrides: dict[str, bool] | None = None,
58
+ *,
59
+ releases: bool = False,
60
+ workflows: bool = False,
61
+ issues: bool = False,
62
+ pull_requests: bool = True,
63
+ quality: bool = True,
64
+ ) -> ResolvedProfile:
65
+ """
66
+ Resolve ``name`` including parents and repository overrides.
67
+
68
+ Args:
69
+ profiles: Named profile definitions.
70
+ name: Profile to resolve.
71
+ overrides: Repository check overrides applied last.
72
+ releases: Used when no profile in the chain sets releases.
73
+ workflows: Used when no profile in the chain sets workflows.
74
+ issues: Used when no profile in the chain sets issues.
75
+ pull_requests: Used when no profile in the chain sets pull requests.
76
+ quality: Used when no profile in the chain sets quality.
77
+
78
+ Returns:
79
+ Effective flags. The chain runs from the named profile to the root.
80
+
81
+ Raises:
82
+ ConfigError: The profile is missing or inheritance is circular.
83
+
84
+ """
85
+
86
+ chain = _inheritance_chain(profiles, name)
87
+ enabled = dict.fromkeys(CHECK_NAMES, False)
88
+ sources = dict.fromkeys(CHECK_NAMES, "default")
89
+ for profile_name in reversed(chain):
90
+ spec = profiles[profile_name]
91
+ _apply_profile(spec, profile_name, enabled, sources)
92
+ defaults = {
93
+ "releases": releases,
94
+ "workflows": workflows,
95
+ "issues": issues,
96
+ "pull_requests": pull_requests,
97
+ "quality": quality,
98
+ }
99
+ for flag, value in defaults.items():
100
+ if sources[flag] == "default":
101
+ enabled[flag] = value
102
+ for check, value in (overrides or {}).items():
103
+ enabled[check] = value
104
+ sources[check] = "repository"
105
+ return ResolvedProfile(
106
+ name=name,
107
+ chain=chain,
108
+ enabled=enabled,
109
+ sources=sources,
110
+ )
111
+
112
+
113
+ def _inheritance_chain(
114
+ profiles: dict[str, ProfileSpec],
115
+ name: str,
116
+ ) -> tuple[str, ...]:
117
+ chain: list[str] = []
118
+ seen: set[str] = set()
119
+ current: str | None = name
120
+ while current is not None:
121
+ if current in seen:
122
+ cycle = " -> ".join([*chain, current])
123
+ raise ConfigError(f"Circular profile inheritance: {cycle}.")
124
+ spec = profiles.get(current)
125
+ if spec is None:
126
+ raise ConfigError(f"Unknown profile: {current}.")
127
+ seen.add(current)
128
+ chain.append(current)
129
+ current = spec.extends
130
+ return tuple(chain)
131
+
132
+
133
+ def _apply_profile(
134
+ spec: ProfileSpec,
135
+ profile_name: str,
136
+ enabled: dict[str, bool],
137
+ sources: dict[str, str],
138
+ ) -> None:
139
+ for check in CHECK_NAMES:
140
+ value = getattr(spec, check)
141
+ if isinstance(value, bool):
142
+ enabled[check] = value
143
+ sources[check] = profile_name
@@ -0,0 +1,54 @@
1
+ """
2
+ Project-wide constants for GitHub Intel.
3
+
4
+ This module contains stable names, version text, and process exit codes.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Final
10
+
11
+ __all__ = [
12
+ "API_VERSION",
13
+ "CHECK_NAMES",
14
+ "DEFAULT_PROFILE",
15
+ "EXIT_AUTH",
16
+ "EXIT_CHECKS",
17
+ "EXIT_CONFIG",
18
+ "EXIT_ERROR",
19
+ "EXIT_NOT_FOUND",
20
+ "EXIT_SUCCESS",
21
+ "EXIT_SYNC",
22
+ "PROGRAM_NAME",
23
+ "PROGRAM_VERSION",
24
+ "PROGRAM_VERSION_STRING",
25
+ "PROJECT_NAME",
26
+ "UNGROUPED",
27
+ "USER_AGENT",
28
+ ]
29
+
30
+ PROGRAM_NAME: Final[str] = "github-intel"
31
+ PROJECT_NAME: Final[str] = "lupaxa-github-intel"
32
+ PROGRAM_VERSION: Final[str] = "0.1.0"
33
+ PROGRAM_VERSION_STRING: Final[str] = f"{PROGRAM_NAME} v{PROGRAM_VERSION}"
34
+
35
+ USER_AGENT: Final[str] = "lupaxa-github-intel"
36
+ API_VERSION: Final[str] = "2022-11-28"
37
+ DEFAULT_PROFILE: Final[str] = "upstream"
38
+ UNGROUPED: Final[str] = "ungrouped"
39
+
40
+ CHECK_NAMES: Final[tuple[str, ...]] = (
41
+ "releases",
42
+ "workflows",
43
+ "issues",
44
+ "pull_requests",
45
+ "quality",
46
+ )
47
+
48
+ EXIT_SUCCESS: Final[int] = 0
49
+ EXIT_ERROR: Final[int] = 1
50
+ EXIT_CONFIG: Final[int] = 2
51
+ EXIT_AUTH: Final[int] = 3
52
+ EXIT_SYNC: Final[int] = 4
53
+ EXIT_NOT_FOUND: Final[int] = 5
54
+ EXIT_CHECKS: Final[int] = 6