@gnost-cli/darwin-arm64 0.5.3 → 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 (65) hide show
  1. package/bundle/_internal/base_library.zip +0 -0
  2. package/bundle/_internal/certifi/cacert.pem +3885 -0
  3. package/bundle/_internal/gnost/__init__.py +1 -1
  4. package/bundle/_internal/gnost/analysis/analyzers/readability_analyzer.py +4 -1
  5. package/bundle/_internal/gnost/analysis/utils/tool_command.py +8 -0
  6. package/bundle/_internal/gnost/changes/__init__.py +1 -0
  7. package/bundle/_internal/gnost/changes/analyzer.py +215 -0
  8. package/bundle/_internal/gnost/changes/findings.py +55 -0
  9. package/bundle/_internal/gnost/changes/impact.py +59 -0
  10. package/bundle/_internal/gnost/changes/refs.py +105 -0
  11. package/bundle/_internal/gnost/changes/render.py +172 -0
  12. package/bundle/_internal/gnost/changes/report.py +124 -0
  13. package/bundle/_internal/gnost/changes/snapshot.py +109 -0
  14. package/bundle/_internal/gnost/ci/__init__.py +1 -0
  15. package/bundle/_internal/gnost/ci/baseline.py +88 -0
  16. package/bundle/_internal/gnost/ci/exit_codes.py +19 -0
  17. package/bundle/_internal/gnost/ci/fingerprint.py +44 -0
  18. package/bundle/_internal/gnost/ci/gate.py +42 -0
  19. package/bundle/_internal/gnost/ci/paths.py +57 -0
  20. package/bundle/_internal/gnost/ci/run.py +135 -0
  21. package/bundle/_internal/gnost/ci/sarif.py +149 -0
  22. package/bundle/_internal/gnost/ci/scorecard.py +95 -0
  23. package/bundle/_internal/gnost/cli/app.py +406 -155
  24. package/bundle/_internal/gnost/cli/commands/changes.py +144 -0
  25. package/bundle/_internal/gnost/cli/commands/init.py +192 -0
  26. package/bundle/_internal/gnost/cli/commands/onboard.py +83 -27
  27. package/bundle/_internal/gnost/cli/commands/remote.py +53 -0
  28. package/bundle/_internal/gnost/cli/commands/show.py +15 -14
  29. package/bundle/_internal/gnost/config/languages.py +19 -4
  30. package/bundle/_internal/gnost/config/settings.py +127 -2
  31. package/bundle/_internal/gnost/core/flow.py +27 -0
  32. package/bundle/_internal/gnost/core/insight_builder.py +3 -1
  33. package/bundle/_internal/gnost/core/risk.py +115 -0
  34. package/bundle/_internal/gnost/reporters/insights_json.py +65 -1
  35. package/bundle/_internal/gnost/reporters/loc_summary.py +3 -3
  36. package/bundle/_internal/gnost/reporters/markdown.py +89 -10
  37. package/bundle/_internal/gnost/reporters/mermaid.py +7 -0
  38. package/bundle/_internal/gnost/reporters/readme.py +11 -6
  39. package/bundle/_internal/gnost/reporters/stats.py +3 -3
  40. package/bundle/_internal/gnost/reporters/summary.py +48 -1
  41. package/bundle/_internal/gnost/scanner/filters.py +45 -12
  42. package/bundle/_internal/gnost/scanner/loc.py +5 -0
  43. package/bundle/_internal/gnost/schemas/insights.schema.json +153 -0
  44. package/bundle/_internal/gnost/utils/footer.py +36 -0
  45. package/bundle/_internal/gnost/utils/integrations.py +346 -0
  46. package/bundle/_internal/gnost/utils/layout.py +111 -0
  47. package/bundle/_internal/gnost/utils/progress.py +6 -3
  48. package/bundle/_internal/gnost/utils/update_check.py +253 -0
  49. package/bundle/_internal/gnost/vcs/__init__.py +1 -0
  50. package/bundle/_internal/gnost/vcs/git.py +181 -0
  51. package/bundle/_internal/gnost/vcs/history.py +404 -0
  52. package/bundle/_internal/gnost/vcs/remote.py +204 -0
  53. package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/METADATA +7 -4
  54. package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/RECORD +88 -30
  55. package/bundle/_internal/gnost-0.6.0rc1.dist-info/REQUESTED +0 -0
  56. package/bundle/_internal/yaml/_yaml.cpython-312-darwin.so +0 -0
  57. package/bundle/gnost +0 -0
  58. package/package.json +1 -1
  59. /package/bundle/_internal/{gnost-0.5.3.dist-info/REQUESTED → certifi/py.typed} +0 -0
  60. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/INSTALLER +0 -0
  61. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/WHEEL +0 -0
  62. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/direct_url.json +0 -0
  63. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/entry_points.txt +0 -0
  64. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/licenses/LICENSE +0 -0
  65. /package/bundle/_internal/{gnost-0.5.3.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: {"exclude": list},
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 {list: "a list", int: "an integer", bool: "true or false"}[expected]
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.3"
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 LANGUAGES
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 ext, stats in data["by_language"].items():
17
- table.add_row(LANGUAGES[ext]["name"], str(stats["files"]), str(stats["loc"]))
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 LANGUAGES
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.scan.root}`\n"
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](docs/flow/function-flow.md).\n",
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](docs/flow/entry-paths.md)\n\n"
234
- "- 🧭 [folder-based Paths](docs/flow/folder-paths.md)\n\n"
235
- "(Complete system flow: [flow/flow-full.md](docs/flow/FLOW-full.md))\n"
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**](./docs/flow/FLOW-full.md)<br>"
263
- "Raw Mermaid: [flow/flow-full.mmd](./docs/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 ext, stats in self.loc_data["by_language"].items():
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]: