@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
|
@@ -8,6 +8,9 @@ reported as warnings; wrong value types are errors that name the key.
|
|
|
8
8
|
Example::
|
|
9
9
|
|
|
10
10
|
exclude = ["legacy", "*.generated.ts"] # skipped by onboard and analyze
|
|
11
|
+
output_dir = ".gnost" # where GNOST writes its files
|
|
12
|
+
check_updates = true # say so when a newer gnost exists
|
|
13
|
+
footer = true # "Generated by GNOST" in the Markdown files
|
|
11
14
|
|
|
12
15
|
[onboard]
|
|
13
16
|
max_edges = 150 # largest diagram drawn file by file
|
|
@@ -22,8 +25,17 @@ Example::
|
|
|
22
25
|
[caution.ranges] # [counts as 0, counts as 1]
|
|
23
26
|
size = [300, 1500]
|
|
24
27
|
|
|
28
|
+
[risk] # files that are fragile AND changing (needs git)
|
|
29
|
+
threshold = 20 # lowest risk listed, 0-100
|
|
30
|
+
limit = 10 # most files listed
|
|
31
|
+
|
|
32
|
+
[history] # how change hotspots are measured (needs git)
|
|
33
|
+
days = 365 # how far back to look
|
|
34
|
+
exclude_authors = ["*[bot]"]
|
|
35
|
+
|
|
25
36
|
[analyze]
|
|
26
37
|
analyzers = ["maintainability", "readability"]
|
|
38
|
+
fail_under = 7.5 # CI: exit 3 when the final score (0-10) is lower
|
|
27
39
|
timeout = 600
|
|
28
40
|
max_findings = 500
|
|
29
41
|
parallel = true
|
|
@@ -36,6 +48,9 @@ import sys
|
|
|
36
48
|
from dataclasses import dataclass, field
|
|
37
49
|
from typing import Any, Dict, List, Optional
|
|
38
50
|
|
|
51
|
+
from gnost.utils.layout import DEFAULT_OUTPUT_DIR
|
|
52
|
+
from gnost.core.risk import RiskSettings
|
|
53
|
+
from gnost.vcs.history import HistorySettings
|
|
39
54
|
from gnost.core.caution import (
|
|
40
55
|
DEFAULT_RANGES,
|
|
41
56
|
DEFAULT_WEIGHTS,
|
|
@@ -49,6 +64,10 @@ except ModuleNotFoundError: # pragma: no cover
|
|
|
49
64
|
|
|
50
65
|
CONFIG_NAME = ".gnost.toml"
|
|
51
66
|
|
|
67
|
+
# Built-in `analyze` defaults (also what `gnost init` writes).
|
|
68
|
+
ANALYZE_TIMEOUT = 900
|
|
69
|
+
ANALYZE_MAX_FINDINGS = 1000
|
|
70
|
+
|
|
52
71
|
|
|
53
72
|
class ConfigError(Exception):
|
|
54
73
|
"""The config file cannot be used; the message names the file and key."""
|
|
@@ -57,14 +76,32 @@ class ConfigError(Exception):
|
|
|
57
76
|
_NUMBER = (int, float)
|
|
58
77
|
# section -> key -> accepted type(s); `None` section is the top level
|
|
59
78
|
SCHEMA: Dict[Optional[str], Dict[str, Any]] = {
|
|
60
|
-
None: {
|
|
79
|
+
None: {
|
|
80
|
+
"exclude": list,
|
|
81
|
+
"output_dir": str,
|
|
82
|
+
"check_updates": bool,
|
|
83
|
+
"footer": bool,
|
|
84
|
+
},
|
|
61
85
|
"onboard": {"max_edges": int, "collapse": int, "depth": int},
|
|
62
86
|
"caution": {"threshold": _NUMBER, "limit": int},
|
|
87
|
+
"risk": {"threshold": _NUMBER, "limit": int, "churn_weight": _NUMBER},
|
|
88
|
+
"history": {
|
|
89
|
+
"enabled": bool,
|
|
90
|
+
"days": int,
|
|
91
|
+
"max_commits": int,
|
|
92
|
+
"recent_days": int,
|
|
93
|
+
"exclude_authors": list,
|
|
94
|
+
"max_files_per_commit": int,
|
|
95
|
+
"min_commits": int,
|
|
96
|
+
"top": int,
|
|
97
|
+
},
|
|
63
98
|
"analyze": {
|
|
64
99
|
"analyzers": list,
|
|
65
100
|
"timeout": int,
|
|
66
101
|
"max_findings": int,
|
|
67
102
|
"parallel": bool,
|
|
103
|
+
"fail_under": _NUMBER,
|
|
104
|
+
"baseline": str,
|
|
68
105
|
},
|
|
69
106
|
}
|
|
70
107
|
_TABLES = {"caution.weights", "caution.ranges"}
|
|
@@ -84,12 +121,54 @@ class GnostConfig:
|
|
|
84
121
|
def exclude(self) -> List[str]:
|
|
85
122
|
return list(self.get(None, "exclude", []))
|
|
86
123
|
|
|
124
|
+
@property
|
|
125
|
+
def check_updates(self) -> bool:
|
|
126
|
+
"""Whether `gnost --version` may look for a newer release."""
|
|
127
|
+
return bool(self.get(None, "check_updates", True))
|
|
128
|
+
|
|
129
|
+
@property
|
|
130
|
+
def footer(self) -> bool:
|
|
131
|
+
"""Whether generated Markdown files end with the "Generated by GNOST" line."""
|
|
132
|
+
return bool(self.get(None, "footer", True))
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def output_dir(self) -> str:
|
|
136
|
+
"""The folder GNOST writes to, relative to the project root (default .gnost)."""
|
|
137
|
+
return str(self.get(None, "output_dir", DEFAULT_OUTPUT_DIR))
|
|
138
|
+
|
|
87
139
|
def pick(self, section: str, key: str, cli_value: Any, default: Any) -> Any:
|
|
88
140
|
"""CLI flag, else config file, else default."""
|
|
89
141
|
if cli_value is not None:
|
|
90
142
|
return cli_value
|
|
91
143
|
return self.get(section, key, default)
|
|
92
144
|
|
|
145
|
+
def risk_settings(self) -> RiskSettings:
|
|
146
|
+
"""Risk settings: the [risk] table over the defaults."""
|
|
147
|
+
base = RiskSettings()
|
|
148
|
+
given = self.values.get("risk", {})
|
|
149
|
+
return RiskSettings(
|
|
150
|
+
threshold=float(given.get("threshold", base.threshold)),
|
|
151
|
+
limit=int(given.get("limit", base.limit)),
|
|
152
|
+
churn_weight=float(given.get("churn_weight", base.churn_weight)),
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
def history_settings(self) -> HistorySettings:
|
|
156
|
+
"""Change-history settings: the [history] table over the defaults."""
|
|
157
|
+
base = HistorySettings()
|
|
158
|
+
given = self.values.get("history", {})
|
|
159
|
+
return HistorySettings(
|
|
160
|
+
enabled=bool(given.get("enabled", base.enabled)),
|
|
161
|
+
days=int(given.get("days", base.days)),
|
|
162
|
+
max_commits=int(given.get("max_commits", base.max_commits)),
|
|
163
|
+
recent_days=int(given.get("recent_days", base.recent_days)),
|
|
164
|
+
exclude_authors=tuple(given.get("exclude_authors", base.exclude_authors)),
|
|
165
|
+
max_files_per_commit=int(
|
|
166
|
+
given.get("max_files_per_commit", base.max_files_per_commit)
|
|
167
|
+
),
|
|
168
|
+
min_commits=int(given.get("min_commits", base.min_commits)),
|
|
169
|
+
top=int(given.get("top", base.top)),
|
|
170
|
+
)
|
|
171
|
+
|
|
93
172
|
def caution_settings(self) -> CautionSettings:
|
|
94
173
|
weights = dict(DEFAULT_WEIGHTS)
|
|
95
174
|
weights.update(self.values.get("caution", {}).get("weights", {}))
|
|
@@ -144,7 +223,12 @@ def load_config(start: str = ".") -> GnostConfig:
|
|
|
144
223
|
def _type_name(expected: Any) -> str:
|
|
145
224
|
if expected is _NUMBER:
|
|
146
225
|
return "a number"
|
|
147
|
-
return {
|
|
226
|
+
return {
|
|
227
|
+
list: "a list",
|
|
228
|
+
int: "an integer",
|
|
229
|
+
bool: "true or false",
|
|
230
|
+
str: "text",
|
|
231
|
+
}[expected]
|
|
148
232
|
|
|
149
233
|
|
|
150
234
|
def _is(value: Any, expected: Any) -> bool:
|
|
@@ -171,6 +255,15 @@ def _validate(raw: Dict[str, Any], config: GnostConfig) -> None:
|
|
|
171
255
|
exclude = values.get("exclude", [])
|
|
172
256
|
if not all(isinstance(p, str) for p in exclude):
|
|
173
257
|
raise ConfigError(f"{where}: 'exclude' must be a list of strings")
|
|
258
|
+
if "output_dir" in values:
|
|
259
|
+
out = values["output_dir"].strip()
|
|
260
|
+
parts = out.replace("\\", "/").split("/")
|
|
261
|
+
if not out or ".." in parts:
|
|
262
|
+
raise ConfigError(
|
|
263
|
+
f"{where}: 'output_dir' must be a folder name or path inside the "
|
|
264
|
+
"project, without '..'"
|
|
265
|
+
)
|
|
266
|
+
values["output_dir"] = out
|
|
174
267
|
config.values = values
|
|
175
268
|
|
|
176
269
|
|
|
@@ -189,6 +282,38 @@ def _validate_section(
|
|
|
189
282
|
else:
|
|
190
283
|
config.warnings.append(f"{where}: unknown setting '{dotted}' (ignored)")
|
|
191
284
|
|
|
285
|
+
if section == "risk":
|
|
286
|
+
if "limit" in out and out["limit"] < 1:
|
|
287
|
+
raise ConfigError(f"{where}: 'risk.limit' must be 1 or more")
|
|
288
|
+
for key in ("threshold", "churn_weight"):
|
|
289
|
+
low, high = (0, 100) if key == "threshold" else (0, 1)
|
|
290
|
+
if key in out and not low <= out[key] <= high:
|
|
291
|
+
raise ConfigError(
|
|
292
|
+
f"{where}: 'risk.{key}' must be between {low} and {high}"
|
|
293
|
+
)
|
|
294
|
+
if section == "history":
|
|
295
|
+
for key in (
|
|
296
|
+
"days",
|
|
297
|
+
"max_commits",
|
|
298
|
+
"recent_days",
|
|
299
|
+
"max_files_per_commit",
|
|
300
|
+
"min_commits",
|
|
301
|
+
"top",
|
|
302
|
+
):
|
|
303
|
+
if key in out and out[key] < 1:
|
|
304
|
+
raise ConfigError(f"{where}: 'history.{key}' must be 1 or more")
|
|
305
|
+
if "exclude_authors" in out and not all(
|
|
306
|
+
isinstance(a, str) for a in out["exclude_authors"]
|
|
307
|
+
):
|
|
308
|
+
raise ConfigError(
|
|
309
|
+
f"{where}: 'history.exclude_authors' must be a list of strings"
|
|
310
|
+
)
|
|
311
|
+
if (
|
|
312
|
+
section == "analyze"
|
|
313
|
+
and "fail_under" in out
|
|
314
|
+
and not 0 <= out["fail_under"] <= 10
|
|
315
|
+
):
|
|
316
|
+
raise ConfigError(f"{where}: 'analyze.fail_under' must be between 0 and 10")
|
|
192
317
|
if section == "analyze" and "analyzers" in out:
|
|
193
318
|
if not all(isinstance(a, str) for a in out["analyzers"]):
|
|
194
319
|
raise ConfigError(f"{where}: 'analyze.analyzers' must be a list of strings")
|
|
@@ -84,6 +84,8 @@ class FlowBuilder:
|
|
|
84
84
|
|
|
85
85
|
for entry in entry_files:
|
|
86
86
|
self._walk(entry, paths, depths)
|
|
87
|
+
for extra in self._unreached_roots(depths):
|
|
88
|
+
self._walk(extra, paths, depths)
|
|
87
89
|
|
|
88
90
|
edges = sorted(
|
|
89
91
|
(src, dst)
|
|
@@ -134,6 +136,31 @@ class FlowBuilder:
|
|
|
134
136
|
for dep in unvisited:
|
|
135
137
|
queue.append(path + [dep])
|
|
136
138
|
|
|
139
|
+
COVERAGE_FLOOR = (
|
|
140
|
+
0.5 # below this share of connected files, the entry misses the app
|
|
141
|
+
)
|
|
142
|
+
|
|
143
|
+
def _unreached_roots(self, depths: Dict[str, int]) -> List[str]:
|
|
144
|
+
"""Top-level importers to walk too, when the entry points reach little of the graph.
|
|
145
|
+
|
|
146
|
+
Frameworks that wire code by scanning (Spring Boot, for one) have an entry class
|
|
147
|
+
that imports nothing from the project, which would leave every diagram empty.
|
|
148
|
+
"""
|
|
149
|
+
connected = {
|
|
150
|
+
n
|
|
151
|
+
for n in self.graph.all_nodes()
|
|
152
|
+
if self.graph.dependencies_of(n) or self.graph.dependents_of(n)
|
|
153
|
+
}
|
|
154
|
+
if not connected or len(connected & set(depths)) >= self.COVERAGE_FLOOR * len(
|
|
155
|
+
connected
|
|
156
|
+
):
|
|
157
|
+
return []
|
|
158
|
+
return sorted(
|
|
159
|
+
r
|
|
160
|
+
for r in self.graph.roots()
|
|
161
|
+
if r not in depths and self.graph.dependencies_of(r)
|
|
162
|
+
)
|
|
163
|
+
|
|
137
164
|
def _resolve_entry_files(self) -> List[str]:
|
|
138
165
|
"""
|
|
139
166
|
Convert EntryPoint objects into concrete files.
|
|
@@ -29,8 +29,9 @@ class InsightBuilder:
|
|
|
29
29
|
flow: FlowResult,
|
|
30
30
|
graph: DependencyGraph,
|
|
31
31
|
caution: Optional[CautionSettings] = None,
|
|
32
|
-
):
|
|
32
|
+
) -> None:
|
|
33
33
|
self.caution = caution or CautionSettings()
|
|
34
|
+
self.caution_scores: List[CautionScore] = []
|
|
34
35
|
self.scan = scan
|
|
35
36
|
self.flow = flow
|
|
36
37
|
self.graph = graph
|
|
@@ -104,6 +105,7 @@ class InsightBuilder:
|
|
|
104
105
|
def _build_caution_areas(self) -> List[CautionInsight]:
|
|
105
106
|
"""Files that are risky to change, from the rule-based caution score."""
|
|
106
107
|
ranked = rank_files(self.scan, self.graph, self.flow.cycles, self.caution)
|
|
108
|
+
self.caution_scores = ranked # every file's score, for the risk calculation
|
|
107
109
|
reported = [s for s in ranked if s.score >= self.caution.threshold]
|
|
108
110
|
return [self._to_insight(s) for s in reported[: self.caution.limit]]
|
|
109
111
|
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
"""Risk: files that are fragile to change AND being changed (caution score x change activity).
|
|
2
|
+
|
|
3
|
+
`RiskCalculator` combines the structural caution score of each file with its change-hotspot
|
|
4
|
+
score from git history. A fragile file nobody touches, or a busy file that is simple, is not
|
|
5
|
+
listed: only the ones that are both. Shown by `gnost onboard` in ONBOARD.md and insights.json.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from typing import Dict, List, Sequence
|
|
13
|
+
|
|
14
|
+
from gnost.core.caution import CautionScore
|
|
15
|
+
from gnost.vcs.history import Hotspot
|
|
16
|
+
|
|
17
|
+
# Plain words for the caution signals, used where a reason is shown.
|
|
18
|
+
REASON_WORDS = {
|
|
19
|
+
"cycles": "circular import",
|
|
20
|
+
"size": "large file",
|
|
21
|
+
"impact": "many files depend on it",
|
|
22
|
+
"coupling": "imports many files",
|
|
23
|
+
"complexity": "complex code",
|
|
24
|
+
"observability": "errors swallowed silently",
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
DEFAULT_THRESHOLD = 20.0
|
|
28
|
+
DEFAULT_LIMIT = 10
|
|
29
|
+
DEFAULT_CHURN_WEIGHT = 1.0
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class RiskSettings:
|
|
34
|
+
"""The [risk] settings: lowest risk listed, how many to list, and how much churn counts."""
|
|
35
|
+
|
|
36
|
+
threshold: float = DEFAULT_THRESHOLD
|
|
37
|
+
limit: int = DEFAULT_LIMIT
|
|
38
|
+
churn_weight: float = DEFAULT_CHURN_WEIGHT # 1 = pure product, 0 = churn ignored
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass
|
|
42
|
+
class RiskItem:
|
|
43
|
+
"""One file's risk with the two scores it comes from, so the number can be explained."""
|
|
44
|
+
|
|
45
|
+
path: str # relative to the scanned folder
|
|
46
|
+
risk: float # 0..100
|
|
47
|
+
structural: float # caution score, 0..100
|
|
48
|
+
churn: float # change-hotspot score, 0..100
|
|
49
|
+
commits: int
|
|
50
|
+
authors: int
|
|
51
|
+
recent_commits: int
|
|
52
|
+
reasons: List[str] = field(default_factory=list) # strongest caution factors
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def why(self) -> str:
|
|
56
|
+
"""The reasons in plain words, for example 'large file, complex code'."""
|
|
57
|
+
return ", ".join(REASON_WORDS.get(r, r) for r in self.reasons)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@dataclass
|
|
61
|
+
class RiskReport:
|
|
62
|
+
"""The ranked risky-and-changing files and the settings that produced them."""
|
|
63
|
+
|
|
64
|
+
items: List[RiskItem]
|
|
65
|
+
settings: RiskSettings
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class RiskCalculator:
|
|
69
|
+
"""risk = structural x (1 - w + w x churn / 100), kept when it reaches the threshold."""
|
|
70
|
+
|
|
71
|
+
REASONS_SHOWN = 2
|
|
72
|
+
|
|
73
|
+
def __init__(self, settings: RiskSettings) -> None:
|
|
74
|
+
self.settings = settings
|
|
75
|
+
|
|
76
|
+
def rank(
|
|
77
|
+
self, structural: Sequence[CautionScore], hotspots: Sequence[Hotspot], root: str
|
|
78
|
+
) -> List[RiskItem]:
|
|
79
|
+
"""Risky-and-changing files, highest risk first; ties broken by path."""
|
|
80
|
+
churn: Dict[str, Hotspot] = {h.change.path: h for h in hotspots}
|
|
81
|
+
items: List[RiskItem] = []
|
|
82
|
+
for score in structural:
|
|
83
|
+
rel = os.path.relpath(score.path, root).replace(os.sep, "/")
|
|
84
|
+
hotspot = churn.get(rel)
|
|
85
|
+
if hotspot is None:
|
|
86
|
+
continue # not changing, so not "changing and fragile"
|
|
87
|
+
risk = round(score.score * self._churn_factor(hotspot.score), 1)
|
|
88
|
+
if risk < self.settings.threshold:
|
|
89
|
+
continue
|
|
90
|
+
change = hotspot.change
|
|
91
|
+
items.append(
|
|
92
|
+
RiskItem(
|
|
93
|
+
path=rel,
|
|
94
|
+
risk=risk,
|
|
95
|
+
structural=score.score,
|
|
96
|
+
churn=hotspot.score,
|
|
97
|
+
commits=change.commits,
|
|
98
|
+
authors=change.author_count,
|
|
99
|
+
recent_commits=change.recent_commits,
|
|
100
|
+
reasons=[f.name for f in score.factors[: self.REASONS_SHOWN]],
|
|
101
|
+
)
|
|
102
|
+
)
|
|
103
|
+
items.sort(key=lambda i: (-i.risk, i.path))
|
|
104
|
+
return items
|
|
105
|
+
|
|
106
|
+
def report(
|
|
107
|
+
self, structural: Sequence[CautionScore], hotspots: Sequence[Hotspot], root: str
|
|
108
|
+
) -> RiskReport:
|
|
109
|
+
"""rank() together with the settings, ready for the reporters."""
|
|
110
|
+
return RiskReport(self.rank(structural, hotspots, root), self.settings)
|
|
111
|
+
|
|
112
|
+
def _churn_factor(self, churn_score: float) -> float:
|
|
113
|
+
"""How much of the structural score survives, from 1 - weight (no churn) to 1."""
|
|
114
|
+
weight = self.settings.churn_weight
|
|
115
|
+
return 1 - weight + weight * churn_score / 100
|
|
@@ -23,11 +23,12 @@ from gnost.core.ranker import HotspotRanker
|
|
|
23
23
|
from gnost.models.insights import OnboardingInsights
|
|
24
24
|
from gnost.scanner.models import ScanResult
|
|
25
25
|
|
|
26
|
-
SCHEMA_VERSION = "1.
|
|
26
|
+
SCHEMA_VERSION = "1.4"
|
|
27
27
|
SCHEMA_PATH = os.path.join(
|
|
28
28
|
os.path.dirname(os.path.dirname(__file__)), "schemas", "insights.schema.json"
|
|
29
29
|
)
|
|
30
30
|
HOTSPOT_LIMIT = 20
|
|
31
|
+
CHANGE_HISTORY_LIMIT = 50
|
|
31
32
|
|
|
32
33
|
|
|
33
34
|
def build_payload(
|
|
@@ -37,6 +38,8 @@ def build_payload(
|
|
|
37
38
|
insights: OnboardingInsights,
|
|
38
39
|
flows: Optional[list] = None,
|
|
39
40
|
call_graph: Any = None,
|
|
41
|
+
changes: Any = None,
|
|
42
|
+
risks: Any = None,
|
|
40
43
|
) -> Dict[str, Any]:
|
|
41
44
|
root = scan.root
|
|
42
45
|
|
|
@@ -82,6 +85,8 @@ def build_payload(
|
|
|
82
85
|
}
|
|
83
86
|
for r in scan.routes
|
|
84
87
|
],
|
|
88
|
+
"change_history": _change_history(changes),
|
|
89
|
+
"risk": _risk(risks),
|
|
85
90
|
"flows": [_flow(f, rel) for f in (flows or [])],
|
|
86
91
|
"callgraph": {
|
|
87
92
|
"functions": len(call_graph.functions) if call_graph else 0,
|
|
@@ -187,3 +192,62 @@ def load_schema() -> Optional[Dict[str, Any]]:
|
|
|
187
192
|
return json.load(f)
|
|
188
193
|
except OSError:
|
|
189
194
|
return None
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _change_history(changes: Any) -> Dict[str, Any]:
|
|
198
|
+
"""Change hotspots from git history (paths relative to the scanned folder)."""
|
|
199
|
+
if changes is None or not changes.history.available:
|
|
200
|
+
history = changes.history if changes is not None else None
|
|
201
|
+
return {
|
|
202
|
+
"available": False,
|
|
203
|
+
"reason": history.reason if history else "not collected",
|
|
204
|
+
"window_days": history.window_days if history else 0,
|
|
205
|
+
"commits_analyzed": 0,
|
|
206
|
+
"files": [],
|
|
207
|
+
}
|
|
208
|
+
return {
|
|
209
|
+
"available": True,
|
|
210
|
+
"reason": None,
|
|
211
|
+
"window_days": changes.history.window_days,
|
|
212
|
+
"commits_analyzed": changes.history.commits,
|
|
213
|
+
"files": [
|
|
214
|
+
{
|
|
215
|
+
"path": h.change.path,
|
|
216
|
+
"score": h.score,
|
|
217
|
+
"commits": h.change.commits,
|
|
218
|
+
"authors": h.change.author_count,
|
|
219
|
+
"recent_commits": h.change.recent_commits,
|
|
220
|
+
"lines_added": h.change.added,
|
|
221
|
+
"lines_removed": h.change.removed,
|
|
222
|
+
"last_changed": _date(h.change.last_changed),
|
|
223
|
+
}
|
|
224
|
+
for h in changes.hotspots[:CHANGE_HISTORY_LIMIT]
|
|
225
|
+
],
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _date(stamp: int) -> str:
|
|
230
|
+
from datetime import datetime, timezone
|
|
231
|
+
|
|
232
|
+
return datetime.fromtimestamp(stamp, tz=timezone.utc).strftime("%Y-%m-%d")
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _risk(risks: Any) -> Dict[str, Any]:
|
|
236
|
+
"""Files that are fragile to change and changing often (caution score x change activity)."""
|
|
237
|
+
items = risks.items[: risks.settings.limit] if risks is not None else []
|
|
238
|
+
return {
|
|
239
|
+
"threshold": risks.settings.threshold if risks is not None else 0,
|
|
240
|
+
"files": [
|
|
241
|
+
{
|
|
242
|
+
"path": i.path,
|
|
243
|
+
"risk": i.risk,
|
|
244
|
+
"structural_score": i.structural,
|
|
245
|
+
"change_score": i.churn,
|
|
246
|
+
"commits": i.commits,
|
|
247
|
+
"authors": i.authors,
|
|
248
|
+
"recent_commits": i.recent_commits,
|
|
249
|
+
"reasons": list(i.reasons),
|
|
250
|
+
}
|
|
251
|
+
for i in items
|
|
252
|
+
],
|
|
253
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
from rich.console import Console
|
|
2
2
|
from rich.table import Table
|
|
3
3
|
|
|
4
|
-
from gnost.config.languages import
|
|
4
|
+
from gnost.config.languages import by_language_name
|
|
5
5
|
|
|
6
6
|
console = Console()
|
|
7
7
|
|
|
@@ -13,7 +13,7 @@ def render(data):
|
|
|
13
13
|
table.add_column("Files", justify="right")
|
|
14
14
|
table.add_column("LOC", justify="right")
|
|
15
15
|
|
|
16
|
-
for
|
|
17
|
-
table.add_row(
|
|
16
|
+
for name, stats in by_language_name(data["by_language"]).items():
|
|
17
|
+
table.add_row(name, str(stats["files"]), str(stats["loc"]))
|
|
18
18
|
|
|
19
19
|
console.print(table)
|
|
@@ -3,11 +3,12 @@ from __future__ import annotations
|
|
|
3
3
|
from typing import Optional
|
|
4
4
|
from pathlib import Path
|
|
5
5
|
from gnost.utils.paths import base, shorten
|
|
6
|
-
from gnost.config.languages import
|
|
6
|
+
from gnost.config.languages import by_language_name
|
|
7
7
|
from gnost.scanner.models import ScanResult
|
|
8
8
|
from gnost.core.flow import FlowResult
|
|
9
9
|
from gnost.reporters.mermaid import DEFAULT_MAX_EDGES, MermaidFlowReporter
|
|
10
10
|
from gnost.models.insights import OnboardingInsights
|
|
11
|
+
from gnost.utils.footer import Footer
|
|
11
12
|
|
|
12
13
|
|
|
13
14
|
class MarkdownReporter:
|
|
@@ -28,7 +29,15 @@ class MarkdownReporter:
|
|
|
28
29
|
mermaid_max_edges: int = DEFAULT_MAX_EDGES,
|
|
29
30
|
mermaid_collapse: Optional[int] = None,
|
|
30
31
|
function_flows: Optional[list] = None,
|
|
32
|
+
changes=None,
|
|
33
|
+
risks=None,
|
|
34
|
+
root_label: Optional[str] = None,
|
|
35
|
+
footer: Optional[Footer] = None,
|
|
31
36
|
):
|
|
37
|
+
self.footer = footer or Footer(False)
|
|
38
|
+
self.root_label = root_label or scan.root
|
|
39
|
+
self.changes = changes
|
|
40
|
+
self.risks = risks
|
|
32
41
|
self.scan = scan
|
|
33
42
|
self.flow = flow
|
|
34
43
|
self.insights = insights
|
|
@@ -48,6 +57,8 @@ class MarkdownReporter:
|
|
|
48
57
|
def write(self):
|
|
49
58
|
content = self._render()
|
|
50
59
|
content += self._path_specific_flows()
|
|
60
|
+
content = self.footer.append(content)
|
|
61
|
+
self.output_file.parent.mkdir(parents=True, exist_ok=True)
|
|
51
62
|
self.output_file.write_text(content, encoding="utf-8")
|
|
52
63
|
|
|
53
64
|
# -------------------------
|
|
@@ -71,6 +82,8 @@ class MarkdownReporter:
|
|
|
71
82
|
[
|
|
72
83
|
self._first_files_md(),
|
|
73
84
|
self._caution_areas_md(),
|
|
85
|
+
self._change_hotspots_md(),
|
|
86
|
+
self._risk_md(),
|
|
74
87
|
self._cycles_md(),
|
|
75
88
|
]
|
|
76
89
|
)
|
|
@@ -99,7 +112,7 @@ class MarkdownReporter:
|
|
|
99
112
|
|
|
100
113
|
return (
|
|
101
114
|
"## Project Overview\n\n"
|
|
102
|
-
f"- **Root:** `{self.
|
|
115
|
+
f"- **Root:** `{self.root_label}`\n"
|
|
103
116
|
f"- **Languages:** {languages}\n"
|
|
104
117
|
f"- **Framework:** {framework}"
|
|
105
118
|
)
|
|
@@ -126,7 +139,7 @@ class MarkdownReporter:
|
|
|
126
139
|
"## Function-level Flow\n",
|
|
127
140
|
"What each entry point calls, function by function (Python only; "
|
|
128
141
|
"calls through other objects such as `self.client.send()` are not "
|
|
129
|
-
"followed). Full diagrams: [function-flow.md](
|
|
142
|
+
"followed). Full diagrams: [function-flow.md](flow/function-flow.md).\n",
|
|
130
143
|
]
|
|
131
144
|
for flow in self.function_flows[: self.FLOW_ENTRIES]:
|
|
132
145
|
entry = flow.entry
|
|
@@ -230,9 +243,9 @@ class MarkdownReporter:
|
|
|
230
243
|
return (
|
|
231
244
|
"## Key Execution Paths\n\n"
|
|
232
245
|
"To understand specific scenarios, see the entry-based execution paths:\n\n"
|
|
233
|
-
"- 📍 [Entry-based Paths](
|
|
234
|
-
"- 🧭 [folder-based Paths](
|
|
235
|
-
"(Complete system flow: [flow/flow-full.md](
|
|
246
|
+
"- 📍 [Entry-based Paths](flow/entry-paths.md)\n\n"
|
|
247
|
+
"- 🧭 [folder-based Paths](flow/folder-paths.md)\n\n"
|
|
248
|
+
"(Complete system flow: [flow/flow-full.md](flow/FLOW-full.md))\n"
|
|
236
249
|
)
|
|
237
250
|
|
|
238
251
|
def _mermaid_flow(self) -> str:
|
|
@@ -259,8 +272,12 @@ class MarkdownReporter:
|
|
|
259
272
|
f"{overview_diagram}\n\n"
|
|
260
273
|
"> 📌 This diagram shows the high-level execution flow.<br>"
|
|
261
274
|
"For the complete flow, see "
|
|
262
|
-
"[**flow/flow-full.md**](./
|
|
263
|
-
"Raw Mermaid: [flow/flow-full.mmd](./
|
|
275
|
+
"[**flow/flow-full.md**](./flow/FLOW-full.md)<br>"
|
|
276
|
+
"Raw Mermaid: [flow/flow-full.mmd](./flow/FLOW-full.mmd)<br>"
|
|
277
|
+
"Every file and import, ungrouped (for tools and AI): "
|
|
278
|
+
"[flow/flow-complete.mmd](./flow/flow-complete.mmd)<br>"
|
|
279
|
+
"Interactive explorer: run `gnost open flow` "
|
|
280
|
+
"(the page is `flow.html` in this folder; it is rebuilt, not committed)"
|
|
264
281
|
)
|
|
265
282
|
|
|
266
283
|
def _summary_and_stats_tables(self) -> str:
|
|
@@ -268,8 +285,7 @@ class MarkdownReporter:
|
|
|
268
285
|
return ""
|
|
269
286
|
|
|
270
287
|
rows = []
|
|
271
|
-
for
|
|
272
|
-
language = LANGUAGES.get(ext, {}).get("name", ext.upper())
|
|
288
|
+
for language, stats in by_language_name(self.loc_data["by_language"]).items():
|
|
273
289
|
rows.append((language, stats))
|
|
274
290
|
|
|
275
291
|
rows.sort(key=lambda item: item[0].lower())
|
|
@@ -307,6 +323,69 @@ class MarkdownReporter:
|
|
|
307
323
|
|
|
308
324
|
return "\n".join(lines)
|
|
309
325
|
|
|
326
|
+
def _change_hotspots_md(self) -> str:
|
|
327
|
+
"""Files that change most often (from git history); empty when there is no history to report."""
|
|
328
|
+
changes = self.changes
|
|
329
|
+
if changes is None:
|
|
330
|
+
return ""
|
|
331
|
+
history = changes.history
|
|
332
|
+
if not history.available:
|
|
333
|
+
if not changes.note_worth_showing:
|
|
334
|
+
return ""
|
|
335
|
+
return f"## Change Hotspots\n\n_Not available: {history.reason}_"
|
|
336
|
+
if not changes.hotspots:
|
|
337
|
+
return (
|
|
338
|
+
"## Change Hotspots\n\n"
|
|
339
|
+
f"_No file changed more than once in the last {history.window_days} days._"
|
|
340
|
+
)
|
|
341
|
+
recent = changes.settings.recent_days
|
|
342
|
+
lines = [
|
|
343
|
+
"## Change Hotspots",
|
|
344
|
+
"",
|
|
345
|
+
f"Files that changed most in the last {history.window_days} days "
|
|
346
|
+
f"({history.commits} commits). A file that changes often and is touched by "
|
|
347
|
+
"many people is where merge conflicts and regressions tend to start.",
|
|
348
|
+
"",
|
|
349
|
+
f"| File | Commits | Authors | Last {recent} days | Lines changed | Last change |",
|
|
350
|
+
"|---|---:|---:|---:|---|---|",
|
|
351
|
+
]
|
|
352
|
+
from gnost.reporters.insights_json import _date
|
|
353
|
+
|
|
354
|
+
for h in changes.hotspots[: changes.settings.top]:
|
|
355
|
+
c = h.change
|
|
356
|
+
lines.append(
|
|
357
|
+
f"| `{c.path}` | {c.commits} | {c.author_count} | {c.recent_commits} "
|
|
358
|
+
f"| +{c.added} / -{c.removed} | {_date(c.last_changed)} |"
|
|
359
|
+
)
|
|
360
|
+
return "\n".join(lines)
|
|
361
|
+
|
|
362
|
+
def _risk_md(self) -> str:
|
|
363
|
+
"""Files that are both fragile and changing; empty when there is no history."""
|
|
364
|
+
risks, changes = self.risks, self.changes
|
|
365
|
+
if risks is None or changes is None or not changes.history.available:
|
|
366
|
+
return ""
|
|
367
|
+
if not risks.items:
|
|
368
|
+
return (
|
|
369
|
+
"## Risky and Changing\n\n"
|
|
370
|
+
"_No file is both fragile to change and changing often._"
|
|
371
|
+
)
|
|
372
|
+
lines = [
|
|
373
|
+
"## Risky and Changing",
|
|
374
|
+
"",
|
|
375
|
+
"Files that are fragile to change (high caution score) and also change often. "
|
|
376
|
+
"Start here when adding tests or reviewing changes. "
|
|
377
|
+
"Risk = caution score scaled by how much the file changes.",
|
|
378
|
+
"",
|
|
379
|
+
"| File | Risk | Caution | Change activity | Why fragile | Commits | Authors |",
|
|
380
|
+
"|---|---:|---:|---:|---|---:|---:|",
|
|
381
|
+
]
|
|
382
|
+
for i in risks.items[: risks.settings.limit]:
|
|
383
|
+
lines.append(
|
|
384
|
+
f"| `{i.path}` | {i.risk:g} | {i.structural:g} | {i.churn:g} "
|
|
385
|
+
f"| {i.why} | {i.commits} | {i.authors} |"
|
|
386
|
+
)
|
|
387
|
+
return "\n".join(lines)
|
|
388
|
+
|
|
310
389
|
def _caution_areas_md(self) -> str:
|
|
311
390
|
lines = ["## ⚠️ Caution Areas"]
|
|
312
391
|
|
|
@@ -383,6 +383,13 @@ class MermaidFlowReporter:
|
|
|
383
383
|
if allowed_nodes and (src not in allowed_nodes or dst not in allowed_nodes):
|
|
384
384
|
continue
|
|
385
385
|
edges.add((src, dst))
|
|
386
|
+
if not edges and allowed_nodes:
|
|
387
|
+
# No core files (a flat project): show the whole flow rather than an empty overview.
|
|
388
|
+
return {
|
|
389
|
+
(s, d)
|
|
390
|
+
for s, d in flow.edges
|
|
391
|
+
if not (self.depth and flow.depths.get(s, 0) >= self.depth)
|
|
392
|
+
}
|
|
386
393
|
return edges
|
|
387
394
|
|
|
388
395
|
def _overview_nodes(self) -> Set[str]:
|