@gnost-cli/darwin-arm64 0.5.3-rc.1 → 0.6.0-rc.1
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.
- package/bundle/_internal/base_library.zip +0 -0
- package/bundle/_internal/bin/ruff +0 -0
- package/bundle/_internal/certifi/cacert.pem +3885 -0
- package/bundle/_internal/gnost/__init__.py +1 -1
- package/bundle/_internal/gnost/analysis/analyzers/readability_analyzer.py +4 -1
- package/bundle/_internal/gnost/analysis/utils/tool_command.py +8 -0
- package/bundle/_internal/gnost/changes/__init__.py +1 -0
- package/bundle/_internal/gnost/changes/analyzer.py +215 -0
- package/bundle/_internal/gnost/changes/findings.py +55 -0
- package/bundle/_internal/gnost/changes/impact.py +59 -0
- package/bundle/_internal/gnost/changes/refs.py +105 -0
- package/bundle/_internal/gnost/changes/render.py +172 -0
- package/bundle/_internal/gnost/changes/report.py +124 -0
- package/bundle/_internal/gnost/changes/snapshot.py +109 -0
- package/bundle/_internal/gnost/ci/__init__.py +1 -0
- package/bundle/_internal/gnost/ci/baseline.py +88 -0
- package/bundle/_internal/gnost/ci/exit_codes.py +19 -0
- package/bundle/_internal/gnost/ci/fingerprint.py +44 -0
- package/bundle/_internal/gnost/ci/gate.py +42 -0
- package/bundle/_internal/gnost/ci/paths.py +57 -0
- package/bundle/_internal/gnost/ci/run.py +135 -0
- package/bundle/_internal/gnost/ci/sarif.py +149 -0
- package/bundle/_internal/gnost/ci/scorecard.py +95 -0
- package/bundle/_internal/gnost/cli/app.py +406 -155
- package/bundle/_internal/gnost/cli/commands/changes.py +144 -0
- package/bundle/_internal/gnost/cli/commands/init.py +192 -0
- package/bundle/_internal/gnost/cli/commands/onboard.py +83 -27
- package/bundle/_internal/gnost/cli/commands/remote.py +53 -0
- package/bundle/_internal/gnost/cli/commands/show.py +15 -14
- package/bundle/_internal/gnost/config/languages.py +19 -4
- package/bundle/_internal/gnost/config/settings.py +127 -2
- package/bundle/_internal/gnost/core/flow.py +27 -0
- package/bundle/_internal/gnost/core/insight_builder.py +3 -1
- package/bundle/_internal/gnost/core/risk.py +115 -0
- package/bundle/_internal/gnost/reporters/insights_json.py +65 -1
- package/bundle/_internal/gnost/reporters/loc_summary.py +3 -3
- package/bundle/_internal/gnost/reporters/markdown.py +89 -10
- package/bundle/_internal/gnost/reporters/mermaid.py +7 -0
- package/bundle/_internal/gnost/reporters/readme.py +11 -6
- package/bundle/_internal/gnost/reporters/stats.py +3 -3
- package/bundle/_internal/gnost/reporters/summary.py +48 -1
- package/bundle/_internal/gnost/scanner/filters.py +45 -12
- package/bundle/_internal/gnost/scanner/loc.py +5 -0
- package/bundle/_internal/gnost/schemas/insights.schema.json +153 -0
- package/bundle/_internal/gnost/utils/footer.py +36 -0
- package/bundle/_internal/gnost/utils/integrations.py +346 -0
- package/bundle/_internal/gnost/utils/layout.py +111 -0
- package/bundle/_internal/gnost/utils/progress.py +6 -3
- package/bundle/_internal/gnost/utils/update_check.py +253 -0
- package/bundle/_internal/gnost/vcs/__init__.py +1 -0
- package/bundle/_internal/gnost/vcs/git.py +181 -0
- package/bundle/_internal/gnost/vcs/history.py +404 -0
- package/bundle/_internal/gnost/vcs/remote.py +204 -0
- package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/METADATA +7 -4
- package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/RECORD +88 -30
- package/bundle/_internal/gnost-0.6.0rc1.dist-info/REQUESTED +0 -0
- package/bundle/_internal/librt/base64.cpython-312-darwin.so +0 -0
- package/bundle/_internal/librt/internal.cpython-312-darwin.so +0 -0
- package/bundle/_internal/yaml/_yaml.cpython-312-darwin.so +0 -0
- package/bundle/gnost +0 -0
- package/package.json +1 -1
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info/REQUESTED → certifi/py.typed} +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/INSTALLER +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/WHEEL +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/direct_url.json +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/entry_points.txt +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/licenses/LICENSE +0 -0
- /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/top_level.txt +0 -0
|
@@ -0,0 +1,404 @@
|
|
|
1
|
+
"""Change history per file: how often, by how many people and how recently files change.
|
|
2
|
+
|
|
3
|
+
`HistoryReader` runs one `git log` call, `LogParser` turns it into counts (following renames and
|
|
4
|
+
skipping bots and giant commits), and `ChangeRanker` scores files from pluggable `Signal`s.
|
|
5
|
+
Used by `gnost onboard` for the Change Hotspots table and the `change_history` JSON field.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import fnmatch
|
|
11
|
+
import os
|
|
12
|
+
import re
|
|
13
|
+
import time
|
|
14
|
+
from abc import ABC, abstractmethod
|
|
15
|
+
from dataclasses import dataclass, field
|
|
16
|
+
from datetime import datetime, timezone
|
|
17
|
+
from typing import Callable, Dict, Iterable, List, Optional, Sequence, Set, Tuple
|
|
18
|
+
|
|
19
|
+
from gnost.vcs.git import GitError, GitRepository, GitRunner, GitUnavailable
|
|
20
|
+
|
|
21
|
+
RECORD = "\x1e"
|
|
22
|
+
FIELD = "\x1f"
|
|
23
|
+
LOG_FORMAT = f"--format={RECORD}%H{FIELD}%aN{FIELD}%at"
|
|
24
|
+
DAY = 86400
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Reason:
|
|
28
|
+
"""Why history is not used. The first two are silent: most folders are not repositories."""
|
|
29
|
+
|
|
30
|
+
NO_GIT = "no_git"
|
|
31
|
+
NOT_A_REPO = "not_repo"
|
|
32
|
+
DISABLED = "disabled"
|
|
33
|
+
EMPTY = "empty"
|
|
34
|
+
SHALLOW = "shallow"
|
|
35
|
+
ERROR = "error"
|
|
36
|
+
SILENT = {NO_GIT, NOT_A_REPO, DISABLED}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class HistorySettings:
|
|
41
|
+
"""The [history] settings: window, filters and how many files to list."""
|
|
42
|
+
|
|
43
|
+
enabled: bool = True
|
|
44
|
+
days: int = 365
|
|
45
|
+
max_commits: int = 5000
|
|
46
|
+
recent_days: int = 90
|
|
47
|
+
exclude_authors: Tuple[str, ...] = ("*[bot]", "dependabot*", "renovate*")
|
|
48
|
+
max_files_per_commit: int = 150 # bigger commits are mass reformats or vendoring
|
|
49
|
+
min_commits: int = 2
|
|
50
|
+
top: int = 15
|
|
51
|
+
allow_shallow: bool = False # set for remote clones; not a .gnost.toml key
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class FileChange:
|
|
56
|
+
"""Everything counted about one file over the window."""
|
|
57
|
+
|
|
58
|
+
path: str
|
|
59
|
+
commits: int = 0
|
|
60
|
+
recent_commits: int = 0
|
|
61
|
+
authors: Set[str] = field(default_factory=set)
|
|
62
|
+
added: int = 0
|
|
63
|
+
removed: int = 0
|
|
64
|
+
last_changed: int = 0 # unix time of the newest change
|
|
65
|
+
|
|
66
|
+
@property
|
|
67
|
+
def author_count(self) -> int:
|
|
68
|
+
"""Number of distinct people who changed the file."""
|
|
69
|
+
return len(self.authors)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class ChangeHistory:
|
|
74
|
+
"""The counted history of a folder, or the reason there is none."""
|
|
75
|
+
|
|
76
|
+
available: bool
|
|
77
|
+
reason_kind: Optional[str] = None
|
|
78
|
+
reason: Optional[str] = None
|
|
79
|
+
window_days: int = 365
|
|
80
|
+
commits: int = 0 # commits that were counted
|
|
81
|
+
skipped_commits: int = 0 # bots and giant commits (merges are excluded by git)
|
|
82
|
+
files: Dict[str, FileChange] = field(default_factory=dict)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
@dataclass(frozen=True)
|
|
86
|
+
class Hotspot:
|
|
87
|
+
"""A file with its change-activity score (0 to 100)."""
|
|
88
|
+
|
|
89
|
+
change: FileChange
|
|
90
|
+
score: float
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@dataclass
|
|
94
|
+
class ChangeInsights:
|
|
95
|
+
"""What onboard reports: the history, the ranked files and the settings used."""
|
|
96
|
+
|
|
97
|
+
history: ChangeHistory
|
|
98
|
+
hotspots: List[Hotspot]
|
|
99
|
+
settings: HistorySettings
|
|
100
|
+
|
|
101
|
+
@property
|
|
102
|
+
def note_worth_showing(self) -> bool:
|
|
103
|
+
"""True when history is missing for a reason the reader should be told."""
|
|
104
|
+
return (
|
|
105
|
+
not self.history.available and self.history.reason_kind not in Reason.SILENT
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
# ------------------------------------------------------------------ parsing
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class LogParser:
|
|
113
|
+
"""Turns `git log --numstat` output (newest commit first) into per-file counts."""
|
|
114
|
+
|
|
115
|
+
_BRACES = re.compile(r"^(.*)\{(.*) => (.*)\}(.*)$")
|
|
116
|
+
|
|
117
|
+
def __init__(self, settings: HistorySettings, now: float) -> None:
|
|
118
|
+
self.settings = settings
|
|
119
|
+
self.now = now
|
|
120
|
+
self._renamed: Dict[str, str] = {} # old path -> the file's name today
|
|
121
|
+
|
|
122
|
+
def parse(self, text: str) -> ChangeHistory:
|
|
123
|
+
"""Count every commit in the log text."""
|
|
124
|
+
history = ChangeHistory(available=True, window_days=self.settings.days)
|
|
125
|
+
recent_after = self.now - self.settings.recent_days * DAY
|
|
126
|
+
for record in text.split(RECORD):
|
|
127
|
+
commit = self._read_record(record)
|
|
128
|
+
if commit is None:
|
|
129
|
+
continue
|
|
130
|
+
author, when, changed = commit
|
|
131
|
+
if self._is_ignored(author, len(changed)):
|
|
132
|
+
history.skipped_commits += 1
|
|
133
|
+
continue
|
|
134
|
+
history.commits += 1
|
|
135
|
+
for path, added, removed in changed:
|
|
136
|
+
entry = history.files.setdefault(path, FileChange(path))
|
|
137
|
+
entry.commits += 1
|
|
138
|
+
entry.authors.add(author)
|
|
139
|
+
entry.added += added
|
|
140
|
+
entry.removed += removed
|
|
141
|
+
entry.last_changed = max(entry.last_changed, when)
|
|
142
|
+
if when >= recent_after:
|
|
143
|
+
entry.recent_commits += 1
|
|
144
|
+
return history
|
|
145
|
+
|
|
146
|
+
def _read_record(
|
|
147
|
+
self, record: str
|
|
148
|
+
) -> Optional[Tuple[str, int, List[Tuple[str, int, int]]]]:
|
|
149
|
+
"""(author, time, [(path, added, removed)]) for one commit, or None if it is junk."""
|
|
150
|
+
if not record.strip():
|
|
151
|
+
return None
|
|
152
|
+
header, _, body = record.partition("\n")
|
|
153
|
+
parts = header.split(FIELD)
|
|
154
|
+
if len(parts) != 3 or not parts[2].isdigit():
|
|
155
|
+
return None
|
|
156
|
+
changed: List[Tuple[str, int, int]] = []
|
|
157
|
+
for line in body.splitlines():
|
|
158
|
+
cols = line.split("\t", 2)
|
|
159
|
+
if len(cols) == 3:
|
|
160
|
+
added, removed, raw = cols
|
|
161
|
+
changed.append(
|
|
162
|
+
(
|
|
163
|
+
self._current_name(raw),
|
|
164
|
+
int(added) if added.isdigit() else 0, # binary files print "-"
|
|
165
|
+
int(removed) if removed.isdigit() else 0,
|
|
166
|
+
)
|
|
167
|
+
)
|
|
168
|
+
return parts[1], int(parts[2]), changed
|
|
169
|
+
|
|
170
|
+
def _current_name(self, raw: str) -> str:
|
|
171
|
+
"""The path a numstat entry refers to today, learning renames as it goes."""
|
|
172
|
+
old, new = self._split_rename(raw)
|
|
173
|
+
target = self._follow(new)
|
|
174
|
+
if old is not None:
|
|
175
|
+
self._renamed[old] = target # older commits used the old name
|
|
176
|
+
return target
|
|
177
|
+
|
|
178
|
+
def _follow(self, path: str) -> str:
|
|
179
|
+
"""Follow recorded renames to the file's current name."""
|
|
180
|
+
hops = 0
|
|
181
|
+
while path in self._renamed and hops < 50:
|
|
182
|
+
path = self._renamed[path]
|
|
183
|
+
hops += 1
|
|
184
|
+
return path
|
|
185
|
+
|
|
186
|
+
def _split_rename(self, raw: str) -> Tuple[Optional[str], str]:
|
|
187
|
+
"""(old path or None, new path) from 'a/{b => c}/d', 'x => y' or a plain path."""
|
|
188
|
+
match = self._BRACES.match(raw)
|
|
189
|
+
if match:
|
|
190
|
+
pre, old, new, post = match.groups()
|
|
191
|
+
return (pre + old + post).replace("//", "/"), (pre + new + post).replace(
|
|
192
|
+
"//", "/"
|
|
193
|
+
)
|
|
194
|
+
if " => " in raw:
|
|
195
|
+
old, new = raw.split(" => ", 1)
|
|
196
|
+
return old, new
|
|
197
|
+
return None, raw
|
|
198
|
+
|
|
199
|
+
def _is_ignored(self, author: str, files_changed: int) -> bool:
|
|
200
|
+
"""Bots and mass-change commits say nothing about individual files."""
|
|
201
|
+
lowered = author.lower()
|
|
202
|
+
is_bot = any(
|
|
203
|
+
fnmatch.fnmatch(lowered, p.lower()) for p in self.settings.exclude_authors
|
|
204
|
+
)
|
|
205
|
+
return is_bot or files_changed > self.settings.max_files_per_commit
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
# ------------------------------------------------------------------ ranking
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
class Signal(ABC):
|
|
212
|
+
"""One measure of change activity with a weight; add a subclass to add a measure."""
|
|
213
|
+
|
|
214
|
+
weight: float = 1.0
|
|
215
|
+
|
|
216
|
+
@abstractmethod
|
|
217
|
+
def value(self, change: FileChange) -> int:
|
|
218
|
+
"""The raw number this signal reads from a file's counts."""
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class CommitsSignal(Signal):
|
|
222
|
+
"""How many commits touched the file."""
|
|
223
|
+
|
|
224
|
+
weight = 0.5
|
|
225
|
+
|
|
226
|
+
def value(self, change: FileChange) -> int:
|
|
227
|
+
return change.commits
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
class RecentSignal(Signal):
|
|
231
|
+
"""How many of those commits are recent."""
|
|
232
|
+
|
|
233
|
+
weight = 0.3
|
|
234
|
+
|
|
235
|
+
def value(self, change: FileChange) -> int:
|
|
236
|
+
return change.recent_commits
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
class AuthorsSignal(Signal):
|
|
240
|
+
"""How many different people changed it."""
|
|
241
|
+
|
|
242
|
+
weight = 0.2
|
|
243
|
+
|
|
244
|
+
def value(self, change: FileChange) -> int:
|
|
245
|
+
return change.author_count
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
class ChangeRanker:
|
|
249
|
+
"""Scores files 0 to 100 as the weighted percentile of each signal among the changed files.
|
|
250
|
+
|
|
251
|
+
Ties are broken by commits, then path, so the same history gives the same order.
|
|
252
|
+
"""
|
|
253
|
+
|
|
254
|
+
DEFAULT_SIGNALS: Sequence[Signal] = (
|
|
255
|
+
CommitsSignal(),
|
|
256
|
+
RecentSignal(),
|
|
257
|
+
AuthorsSignal(),
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
def __init__(
|
|
261
|
+
self, settings: HistorySettings, signals: Optional[Sequence[Signal]] = None
|
|
262
|
+
) -> None:
|
|
263
|
+
self.settings = settings
|
|
264
|
+
self.signals = tuple(signals or self.DEFAULT_SIGNALS)
|
|
265
|
+
|
|
266
|
+
def rank(
|
|
267
|
+
self, history: ChangeHistory, keep: Optional[Set[str]] = None
|
|
268
|
+
) -> List[Hotspot]:
|
|
269
|
+
"""Hotspots for files changed at least min_commits times (and in `keep`, if given)."""
|
|
270
|
+
files = [
|
|
271
|
+
f
|
|
272
|
+
for f in history.files.values()
|
|
273
|
+
if f.commits >= self.settings.min_commits
|
|
274
|
+
and (keep is None or f.path in keep)
|
|
275
|
+
]
|
|
276
|
+
if not files:
|
|
277
|
+
return []
|
|
278
|
+
total = sum(s.weight for s in self.signals)
|
|
279
|
+
columns = [
|
|
280
|
+
(s.weight, self._percentiles([s.value(f) for f in files]))
|
|
281
|
+
for s in self.signals
|
|
282
|
+
]
|
|
283
|
+
ranked = [
|
|
284
|
+
Hotspot(f, round(100 * sum(w * col[i] for w, col in columns) / total, 1))
|
|
285
|
+
for i, f in enumerate(files)
|
|
286
|
+
]
|
|
287
|
+
ranked.sort(key=lambda h: (-h.score, -h.change.commits, h.change.path))
|
|
288
|
+
return ranked
|
|
289
|
+
|
|
290
|
+
@staticmethod
|
|
291
|
+
def _percentiles(values: List[int]) -> List[float]:
|
|
292
|
+
"""For each value, the share of the others it beats (ties count half)."""
|
|
293
|
+
n = len(values)
|
|
294
|
+
if n == 1:
|
|
295
|
+
return [1.0]
|
|
296
|
+
ordered = sorted(values)
|
|
297
|
+
return [
|
|
298
|
+
(
|
|
299
|
+
sum(1 for o in ordered if o < v)
|
|
300
|
+
+ (sum(1 for o in ordered if o == v) - 1) / 2.0
|
|
301
|
+
)
|
|
302
|
+
/ (n - 1)
|
|
303
|
+
for v in values
|
|
304
|
+
]
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
# ------------------------------------------------------------------ reading
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
class HistoryReader:
|
|
311
|
+
"""Reads the change history of a folder from git; never raises.
|
|
312
|
+
|
|
313
|
+
The git runner and the clock are arguments so tests need no patching.
|
|
314
|
+
"""
|
|
315
|
+
|
|
316
|
+
def __init__(
|
|
317
|
+
self,
|
|
318
|
+
settings: HistorySettings,
|
|
319
|
+
runner: Optional[GitRunner] = None,
|
|
320
|
+
clock: Callable[[], float] = time.time,
|
|
321
|
+
) -> None:
|
|
322
|
+
self.settings = settings
|
|
323
|
+
self.runner = runner or GitRunner()
|
|
324
|
+
self.clock = clock
|
|
325
|
+
|
|
326
|
+
def analyze(self, scan_root: str, scanned: Iterable[str]) -> ChangeInsights:
|
|
327
|
+
"""History plus the ranked hotspots among the scanned files (paths relative to scan_root)."""
|
|
328
|
+
history = self.read(scan_root)
|
|
329
|
+
hotspots = (
|
|
330
|
+
ChangeRanker(self.settings).rank(history, set(scanned))
|
|
331
|
+
if history.available
|
|
332
|
+
else []
|
|
333
|
+
)
|
|
334
|
+
return ChangeInsights(
|
|
335
|
+
history=history, hotspots=hotspots, settings=self.settings
|
|
336
|
+
)
|
|
337
|
+
|
|
338
|
+
def read(self, scan_root: str) -> ChangeHistory:
|
|
339
|
+
"""The counted history of scan_root, or a ChangeHistory that says why there is none."""
|
|
340
|
+
if not self.settings.enabled:
|
|
341
|
+
return self._unavailable(
|
|
342
|
+
Reason.DISABLED, "history is switched off in .gnost.toml"
|
|
343
|
+
)
|
|
344
|
+
try:
|
|
345
|
+
repo = GitRepository.containing(scan_root, self.runner)
|
|
346
|
+
except GitUnavailable as exc:
|
|
347
|
+
# Mention it only when the folder looks like a repository.
|
|
348
|
+
kind = Reason.ERROR if self._has_git_dir(scan_root) else Reason.NO_GIT
|
|
349
|
+
return self._unavailable(kind, str(exc))
|
|
350
|
+
if repo is None:
|
|
351
|
+
return self._unavailable(
|
|
352
|
+
Reason.NOT_A_REPO,
|
|
353
|
+
"this folder is not inside a git repository, so there is no history",
|
|
354
|
+
)
|
|
355
|
+
problem = repo.history_problem(self.settings.allow_shallow)
|
|
356
|
+
if problem:
|
|
357
|
+
return self._unavailable(
|
|
358
|
+
Reason.SHALLOW if "shallow" in problem else Reason.EMPTY, problem
|
|
359
|
+
)
|
|
360
|
+
now = self.clock()
|
|
361
|
+
try:
|
|
362
|
+
log = repo.run(self._log_command(now), cwd=scan_root)
|
|
363
|
+
except GitError as exc:
|
|
364
|
+
return self._unavailable(Reason.ERROR, str(exc))
|
|
365
|
+
return LogParser(self.settings, now).parse(log)
|
|
366
|
+
|
|
367
|
+
def _log_command(self, now: float) -> List[str]:
|
|
368
|
+
"""The one git log call: numstat, renames, mailmap, relative to the scanned folder."""
|
|
369
|
+
since = datetime.fromtimestamp(now - self.settings.days * DAY, tz=timezone.utc)
|
|
370
|
+
return [
|
|
371
|
+
"log",
|
|
372
|
+
"--no-merges",
|
|
373
|
+
"--use-mailmap",
|
|
374
|
+
"-M",
|
|
375
|
+
"--numstat",
|
|
376
|
+
"--relative",
|
|
377
|
+
f"--since={since:%Y-%m-%d}",
|
|
378
|
+
"-n",
|
|
379
|
+
str(self.settings.max_commits),
|
|
380
|
+
LOG_FORMAT,
|
|
381
|
+
"--",
|
|
382
|
+
".",
|
|
383
|
+
]
|
|
384
|
+
|
|
385
|
+
def _unavailable(self, kind: str, reason: str) -> ChangeHistory:
|
|
386
|
+
"""A ChangeHistory that records why there is none."""
|
|
387
|
+
return ChangeHistory(
|
|
388
|
+
available=False,
|
|
389
|
+
reason_kind=kind,
|
|
390
|
+
reason=reason,
|
|
391
|
+
window_days=self.settings.days,
|
|
392
|
+
)
|
|
393
|
+
|
|
394
|
+
@staticmethod
|
|
395
|
+
def _has_git_dir(path: str) -> bool:
|
|
396
|
+
"""True if path or a parent folder has a .git entry."""
|
|
397
|
+
current = os.path.abspath(path)
|
|
398
|
+
while True:
|
|
399
|
+
if os.path.exists(os.path.join(current, ".git")):
|
|
400
|
+
return True
|
|
401
|
+
parent = os.path.dirname(current)
|
|
402
|
+
if parent == current:
|
|
403
|
+
return False
|
|
404
|
+
current = parent
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
"""Cloning a remote repository safely so GNOST can read it.
|
|
2
|
+
|
|
3
|
+
`RemoteUrl` recognises https and ssh addresses (and nothing else). `RemoteClone` makes a
|
|
4
|
+
partial clone in a temporary folder with hooks, symlinks and submodules off, a time and a size
|
|
5
|
+
limit, and always removes it. A repository you do not trust is only ever read, never run.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
import re
|
|
12
|
+
import shutil
|
|
13
|
+
import tempfile
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from types import TracebackType
|
|
16
|
+
from typing import Dict, List, Optional, Sequence, Type
|
|
17
|
+
|
|
18
|
+
from gnost.vcs.git import GitError, GitRunner
|
|
19
|
+
|
|
20
|
+
SCP_STYLE = re.compile(r"^[\w.-]+@[\w.-]+:[\w./~-]+$") # git@github.com:owner/repo.git
|
|
21
|
+
FALLBACK_DEPTH = 500
|
|
22
|
+
MB = 1024 * 1024
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class RemoteError(GitError):
|
|
26
|
+
"""The address is not allowed or the clone failed; the message tells the user what to do."""
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class RemoteUrl:
|
|
31
|
+
"""A repository address GNOST is willing to clone."""
|
|
32
|
+
|
|
33
|
+
text: str
|
|
34
|
+
|
|
35
|
+
@staticmethod
|
|
36
|
+
def looks_remote(text: str) -> bool:
|
|
37
|
+
"""True when the argument is an address rather than a folder on disk."""
|
|
38
|
+
lowered = text.lower()
|
|
39
|
+
return lowered.startswith(
|
|
40
|
+
("http://", "https://", "ssh://", "git://", "ext::")
|
|
41
|
+
) or bool(SCP_STYLE.match(text) and not os.path.exists(text))
|
|
42
|
+
|
|
43
|
+
@classmethod
|
|
44
|
+
def parse(cls, text: str) -> "RemoteUrl":
|
|
45
|
+
"""Accept https:// and ssh addresses; refuse anything that could run a program."""
|
|
46
|
+
value = text.strip()
|
|
47
|
+
lowered = value.lower()
|
|
48
|
+
if value.startswith("-") or any(c in value for c in "\n\r\0 "):
|
|
49
|
+
raise RemoteError(f"not a valid repository address: {text!r}")
|
|
50
|
+
if lowered.startswith(("https://", "ssh://")) or SCP_STYLE.match(value):
|
|
51
|
+
return cls(value)
|
|
52
|
+
if lowered.startswith(("http://", "git://")):
|
|
53
|
+
raise RemoteError(
|
|
54
|
+
"plain http:// and git:// addresses are not encrypted; use the https:// address"
|
|
55
|
+
)
|
|
56
|
+
raise RemoteError(
|
|
57
|
+
f"unsupported repository address {text!r}; use https://... or git@host:owner/repo"
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
@property
|
|
61
|
+
def name(self) -> str:
|
|
62
|
+
"""The repository name, for messages."""
|
|
63
|
+
tail = re.split(r"[/:]", self.text.rstrip("/"))[-1]
|
|
64
|
+
return tail[:-4] if tail.endswith(".git") else tail
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass(frozen=True)
|
|
68
|
+
class CloneLimits:
|
|
69
|
+
"""How long a clone may take and how big the checked out files may get."""
|
|
70
|
+
|
|
71
|
+
timeout: int = 600 # seconds
|
|
72
|
+
max_megabytes: int = 500
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class RemoteClone:
|
|
76
|
+
"""Clones one address into a temporary folder; `with` removes it again, even on Ctrl+C.
|
|
77
|
+
|
|
78
|
+
Safe defaults: no hooks, no submodules, no symlinks, no prompts, only https and ssh.
|
|
79
|
+
"""
|
|
80
|
+
|
|
81
|
+
def __init__(
|
|
82
|
+
self,
|
|
83
|
+
url: RemoteUrl,
|
|
84
|
+
ref: Optional[str] = None,
|
|
85
|
+
limits: Optional[CloneLimits] = None,
|
|
86
|
+
runner: Optional[GitRunner] = None,
|
|
87
|
+
protocols: Sequence[str] = ("https", "ssh"),
|
|
88
|
+
) -> None:
|
|
89
|
+
self.url = url
|
|
90
|
+
self.ref = ref
|
|
91
|
+
self.limits = limits or CloneLimits()
|
|
92
|
+
self.runner = runner or GitRunner(timeout=self.limits.timeout)
|
|
93
|
+
self.protocols = tuple(protocols)
|
|
94
|
+
self._temp: Optional[str] = None
|
|
95
|
+
self.folder = ""
|
|
96
|
+
|
|
97
|
+
def __enter__(self) -> str:
|
|
98
|
+
self._temp = tempfile.mkdtemp(prefix="gnost-clone-")
|
|
99
|
+
self.folder = os.path.join(self._temp, self.url.name or "repo")
|
|
100
|
+
try:
|
|
101
|
+
self._clone()
|
|
102
|
+
self._check_size()
|
|
103
|
+
except BaseException:
|
|
104
|
+
self.__exit__(None, None, None)
|
|
105
|
+
raise
|
|
106
|
+
return os.path.realpath(self.folder)
|
|
107
|
+
|
|
108
|
+
def __exit__(
|
|
109
|
+
self,
|
|
110
|
+
exc_type: Optional[Type[BaseException]],
|
|
111
|
+
exc: Optional[BaseException],
|
|
112
|
+
tb: Optional[TracebackType],
|
|
113
|
+
) -> None:
|
|
114
|
+
if self._temp:
|
|
115
|
+
shutil.rmtree(self._temp, ignore_errors=True)
|
|
116
|
+
self._temp = None
|
|
117
|
+
|
|
118
|
+
# ------------------------------------------------------------ steps
|
|
119
|
+
|
|
120
|
+
def _clone(self) -> None:
|
|
121
|
+
"""Partial clone first; a plain shallow clone if the server cannot filter."""
|
|
122
|
+
try:
|
|
123
|
+
self._git(["--filter=blob:none"])
|
|
124
|
+
except GitError as first:
|
|
125
|
+
shutil.rmtree(self.folder, ignore_errors=True)
|
|
126
|
+
try:
|
|
127
|
+
self._git([f"--depth={FALLBACK_DEPTH}"])
|
|
128
|
+
except GitError as second:
|
|
129
|
+
raise RemoteError(self._explain(second, first)) from second
|
|
130
|
+
|
|
131
|
+
def _git(self, extra: List[str]) -> None:
|
|
132
|
+
args = [
|
|
133
|
+
"-c",
|
|
134
|
+
"core.hooksPath=" + os.devnull,
|
|
135
|
+
"-c",
|
|
136
|
+
"core.symlinks=false",
|
|
137
|
+
"-c",
|
|
138
|
+
"core.fsmonitor=false",
|
|
139
|
+
"-c",
|
|
140
|
+
"protocol.allow=never",
|
|
141
|
+
*[
|
|
142
|
+
part
|
|
143
|
+
for proto in self.protocols
|
|
144
|
+
for part in ("-c", f"protocol.{proto}.allow=always")
|
|
145
|
+
],
|
|
146
|
+
"clone",
|
|
147
|
+
"--no-tags",
|
|
148
|
+
"--single-branch",
|
|
149
|
+
"--no-recurse-submodules",
|
|
150
|
+
*extra,
|
|
151
|
+
]
|
|
152
|
+
if self.ref:
|
|
153
|
+
args += ["--branch", self.ref]
|
|
154
|
+
args += ["--", self.url.text, self.folder]
|
|
155
|
+
self.runner.run(
|
|
156
|
+
args, cwd=self._temp or ".", timeout=self.limits.timeout, env=self._env()
|
|
157
|
+
)
|
|
158
|
+
|
|
159
|
+
@staticmethod
|
|
160
|
+
def _env() -> Dict[str, str]:
|
|
161
|
+
"""No prompts, no askpass helper, ssh must never wait for a password."""
|
|
162
|
+
return {
|
|
163
|
+
"GIT_TERMINAL_PROMPT": "0",
|
|
164
|
+
"GIT_ASKPASS": "echo",
|
|
165
|
+
"GIT_SSH_COMMAND": "ssh -o BatchMode=yes",
|
|
166
|
+
"GIT_CONFIG_NOSYSTEM": "1",
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
def _check_size(self) -> None:
|
|
170
|
+
"""Refuse a checkout bigger than the limit."""
|
|
171
|
+
total = 0
|
|
172
|
+
for base, _dirs, files in os.walk(self.folder):
|
|
173
|
+
for name in files:
|
|
174
|
+
try:
|
|
175
|
+
total += os.lstat(os.path.join(base, name)).st_size
|
|
176
|
+
except OSError:
|
|
177
|
+
continue
|
|
178
|
+
if total > self.limits.max_megabytes * MB:
|
|
179
|
+
raise RemoteError(
|
|
180
|
+
f"{self.url.name} is larger than {self.limits.max_megabytes} MB; "
|
|
181
|
+
"clone it yourself and run GNOST on the folder"
|
|
182
|
+
)
|
|
183
|
+
|
|
184
|
+
def _explain(self, error: GitError, first: GitError) -> str:
|
|
185
|
+
"""A short, actionable message for a failed clone."""
|
|
186
|
+
text = f"{error}".lower() + f" {first}".lower()
|
|
187
|
+
if "timed out" in text or "took longer" in text:
|
|
188
|
+
return (
|
|
189
|
+
f"cloning {self.url.name} took longer than {self.limits.timeout} seconds; "
|
|
190
|
+
"clone it yourself and run GNOST on the folder"
|
|
191
|
+
)
|
|
192
|
+
if (
|
|
193
|
+
"authentication" in text
|
|
194
|
+
or "permission denied" in text
|
|
195
|
+
or "could not read" in text
|
|
196
|
+
):
|
|
197
|
+
return (
|
|
198
|
+
f"could not clone {self.url.name}: access was refused. "
|
|
199
|
+
"GNOST never asks for a password; use a public https:// address, or clone it "
|
|
200
|
+
"yourself with your credentials and run GNOST on the folder"
|
|
201
|
+
)
|
|
202
|
+
if "not found" in text or "does not exist" in text:
|
|
203
|
+
return f"could not clone {self.url.name}: the repository or branch was not found"
|
|
204
|
+
return f"could not clone {self.url.name}: {error}"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gnost
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.0rc1
|
|
4
4
|
Summary: GNOST — Codebase Knowledge
|
|
5
5
|
Author-email: Mohd Zain <zainmohd1998@gmail.com>
|
|
6
6
|
License: MIT License
|
|
@@ -68,8 +68,9 @@ Good for first-day onboarding, audits and exploring code you did not write.
|
|
|
68
68
|
- **Execution flow:** Mermaid diagrams of imports, plus function-level flow for Python.
|
|
69
69
|
- **Hotspot files and caution areas:** the files most worth reading first, and the risky ones to read carefully.
|
|
70
70
|
- **Circular imports**, listed and drawn.
|
|
71
|
-
- **`ONBOARD.md`:** a written guide to the repository,
|
|
71
|
+
- **`ONBOARD.md`:** a written guide to the repository, plus the same facts as JSON for tools and AI, all saved in a `.gnost/` folder.
|
|
72
72
|
- **Quality analysis:** maintainability, robustness, observability and readability, with a score and prioritized findings (Python projects).
|
|
73
|
+
- **Any repository by address:** `gnost onboard https://github.com/owner/repo` clones it read only, writes the results to your current folder and deletes the clone. Nothing in the repository is run.
|
|
73
74
|
- **Languages:** Python, JavaScript, TypeScript and Java.
|
|
74
75
|
|
|
75
76
|
## Install
|
|
@@ -96,9 +97,8 @@ Requires Python 3.9 or newer.
|
|
|
96
97
|
## Usage
|
|
97
98
|
|
|
98
99
|
```bash
|
|
99
|
-
gnost onboard . #
|
|
100
|
+
gnost onboard . # writes the .gnost/ folder: guide, diagrams, JSON, explorer
|
|
100
101
|
gnost onboard . --layered --depth 3
|
|
101
|
-
gnost onboard . --json # also write docs/insights/gnost_insights.json
|
|
102
102
|
gnost summary . # languages, files and lines of code
|
|
103
103
|
gnost stats . # detailed stats per language
|
|
104
104
|
gnost folders . # lines of code by folder
|
|
@@ -106,6 +106,9 @@ gnost files . # largest files
|
|
|
106
106
|
gnost analyze . # quality report
|
|
107
107
|
gnost analyze . --parallel -o # run analyzers in parallel and open the report
|
|
108
108
|
gnost open flow # interactive flow explorer in your browser
|
|
109
|
+
gnost changes origin/main # what your change touches: blast radius, risk, new cycles
|
|
110
|
+
gnost onboard https://github.com/owner/repo # any public repository (read only)
|
|
111
|
+
gnost init # write a complete .gnost.toml
|
|
109
112
|
```
|
|
110
113
|
|
|
111
114
|
Add an optional `.gnost.toml` at the repository root for excludes, weights and thresholds. Command-line flags win over the file.
|