@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.
Files changed (68) hide show
  1. package/bundle/_internal/base_library.zip +0 -0
  2. package/bundle/_internal/bin/ruff +0 -0
  3. package/bundle/_internal/certifi/cacert.pem +3885 -0
  4. package/bundle/_internal/gnost/__init__.py +1 -1
  5. package/bundle/_internal/gnost/analysis/analyzers/readability_analyzer.py +4 -1
  6. package/bundle/_internal/gnost/analysis/utils/tool_command.py +8 -0
  7. package/bundle/_internal/gnost/changes/__init__.py +1 -0
  8. package/bundle/_internal/gnost/changes/analyzer.py +215 -0
  9. package/bundle/_internal/gnost/changes/findings.py +55 -0
  10. package/bundle/_internal/gnost/changes/impact.py +59 -0
  11. package/bundle/_internal/gnost/changes/refs.py +105 -0
  12. package/bundle/_internal/gnost/changes/render.py +172 -0
  13. package/bundle/_internal/gnost/changes/report.py +124 -0
  14. package/bundle/_internal/gnost/changes/snapshot.py +109 -0
  15. package/bundle/_internal/gnost/ci/__init__.py +1 -0
  16. package/bundle/_internal/gnost/ci/baseline.py +88 -0
  17. package/bundle/_internal/gnost/ci/exit_codes.py +19 -0
  18. package/bundle/_internal/gnost/ci/fingerprint.py +44 -0
  19. package/bundle/_internal/gnost/ci/gate.py +42 -0
  20. package/bundle/_internal/gnost/ci/paths.py +57 -0
  21. package/bundle/_internal/gnost/ci/run.py +135 -0
  22. package/bundle/_internal/gnost/ci/sarif.py +149 -0
  23. package/bundle/_internal/gnost/ci/scorecard.py +95 -0
  24. package/bundle/_internal/gnost/cli/app.py +406 -155
  25. package/bundle/_internal/gnost/cli/commands/changes.py +144 -0
  26. package/bundle/_internal/gnost/cli/commands/init.py +192 -0
  27. package/bundle/_internal/gnost/cli/commands/onboard.py +83 -27
  28. package/bundle/_internal/gnost/cli/commands/remote.py +53 -0
  29. package/bundle/_internal/gnost/cli/commands/show.py +15 -14
  30. package/bundle/_internal/gnost/config/languages.py +19 -4
  31. package/bundle/_internal/gnost/config/settings.py +127 -2
  32. package/bundle/_internal/gnost/core/flow.py +27 -0
  33. package/bundle/_internal/gnost/core/insight_builder.py +3 -1
  34. package/bundle/_internal/gnost/core/risk.py +115 -0
  35. package/bundle/_internal/gnost/reporters/insights_json.py +65 -1
  36. package/bundle/_internal/gnost/reporters/loc_summary.py +3 -3
  37. package/bundle/_internal/gnost/reporters/markdown.py +89 -10
  38. package/bundle/_internal/gnost/reporters/mermaid.py +7 -0
  39. package/bundle/_internal/gnost/reporters/readme.py +11 -6
  40. package/bundle/_internal/gnost/reporters/stats.py +3 -3
  41. package/bundle/_internal/gnost/reporters/summary.py +48 -1
  42. package/bundle/_internal/gnost/scanner/filters.py +45 -12
  43. package/bundle/_internal/gnost/scanner/loc.py +5 -0
  44. package/bundle/_internal/gnost/schemas/insights.schema.json +153 -0
  45. package/bundle/_internal/gnost/utils/footer.py +36 -0
  46. package/bundle/_internal/gnost/utils/integrations.py +346 -0
  47. package/bundle/_internal/gnost/utils/layout.py +111 -0
  48. package/bundle/_internal/gnost/utils/progress.py +6 -3
  49. package/bundle/_internal/gnost/utils/update_check.py +253 -0
  50. package/bundle/_internal/gnost/vcs/__init__.py +1 -0
  51. package/bundle/_internal/gnost/vcs/git.py +181 -0
  52. package/bundle/_internal/gnost/vcs/history.py +404 -0
  53. package/bundle/_internal/gnost/vcs/remote.py +204 -0
  54. package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/METADATA +7 -4
  55. package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/RECORD +88 -30
  56. package/bundle/_internal/gnost-0.6.0rc1.dist-info/REQUESTED +0 -0
  57. package/bundle/_internal/librt/base64.cpython-312-darwin.so +0 -0
  58. package/bundle/_internal/librt/internal.cpython-312-darwin.so +0 -0
  59. package/bundle/_internal/yaml/_yaml.cpython-312-darwin.so +0 -0
  60. package/bundle/gnost +0 -0
  61. package/package.json +1 -1
  62. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info/REQUESTED → certifi/py.typed} +0 -0
  63. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/INSTALLER +0 -0
  64. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/WHEEL +0 -0
  65. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/direct_url.json +0 -0
  66. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/entry_points.txt +0 -0
  67. /package/bundle/_internal/{gnost-0.5.3rc1.dist-info → gnost-0.6.0rc1.dist-info}/licenses/LICENSE +0 -0
  68. /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.5.3rc1
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, with optional JSON output for tools and AI.
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 . # ONBOARD.md and Mermaid diagrams in docs/flow
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.