@gnost-cli/windows-x64 0.5.3 → 0.6.0-rc.3

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/bandit-1.9.4.dist-info/RECORD +3 -3
  2. package/bundle/_internal/base_library.zip +0 -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 +216 -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 +125 -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 +137 -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 +84 -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 +63 -0
  45. package/bundle/_internal/gnost/utils/fs.py +28 -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 +407 -0
  53. package/bundle/_internal/gnost/vcs/remote.py +204 -0
  54. package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/METADATA +7 -4
  55. package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/RECORD +91 -31
  56. package/bundle/_internal/mypy-2.4.1.dist-info/RECORD +5 -5
  57. package/bundle/_internal/radon-6.0.1.dist-info/RECORD +1 -1
  58. package/bundle/_internal/tqdm-4.70.1.dist-info/RECORD +1 -1
  59. package/bundle/_internal/yaml/_yaml.cp312-win_amd64.pyd +0 -0
  60. package/bundle/gnost.exe +0 -0
  61. package/package.json +1 -1
  62. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/INSTALLER +0 -0
  63. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/REQUESTED +0 -0
  64. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/WHEEL +0 -0
  65. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/direct_url.json +0 -0
  66. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/entry_points.txt +0 -0
  67. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/licenses/LICENSE +0 -0
  68. /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc3.dist-info}/top_level.txt +0 -0
@@ -0,0 +1,144 @@
1
+ """`gnost changes BASE[..HEAD]`: what a change touches, with risk and blast radius.
2
+
3
+ `ChangesCommand` resolves the refs, runs the ChangeAnalyzer, writes `.gnost/changes/` (Markdown
4
+ and JSON) and prints the chosen view. Returns an exit code, never raises for user mistakes.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import os
11
+ import sys
12
+ from typing import Any, Dict, Optional
13
+
14
+ from gnost.changes.analyzer import ChangeAnalyzer
15
+ from gnost.changes.impact import DEFAULT_DEPTH
16
+ from gnost.changes.refs import RefError, RefRange
17
+ from gnost.changes.report import ChangeReport
18
+ from gnost.changes.render import MarkdownRenderer, TextRenderer
19
+ from gnost.ci.exit_codes import ExitCode
20
+ from gnost.config.settings import ConfigError, load_config
21
+ from gnost.utils.footer import Footer
22
+ from gnost.utils.layout import LEGACY_OUTPUT_PATHS, OutputLayout
23
+ from gnost.vcs.git import GitError, GitRepository, GitUnavailable
24
+
25
+ FORMATS = ("text", "markdown", "json")
26
+
27
+
28
+ class ChangesCommand:
29
+ """One run of `gnost changes` for a project folder."""
30
+
31
+ def __init__(
32
+ self,
33
+ path: str,
34
+ refs: str,
35
+ depth: int = DEFAULT_DEPTH,
36
+ output_format: str = "text",
37
+ findings: bool = False,
38
+ compare_base: bool = True,
39
+ write: bool = True,
40
+ output_root: Optional[str] = None,
41
+ remote: bool = False,
42
+ ) -> None:
43
+ self.path = os.path.realpath(path)
44
+ self.refs = refs
45
+ self.depth = depth
46
+ self.output_format = output_format
47
+ self.findings = findings
48
+ self.compare_base = compare_base
49
+ self.write = write
50
+ self.output_root = output_root
51
+ self.remote = remote
52
+
53
+ def run(self) -> int:
54
+ """Run the analysis and report. 0 on success, 2 for a usage problem, 1 on errors."""
55
+ try:
56
+ # a remote repository's own config is never read
57
+ config = load_config(self.output_root if self.remote else self.path)
58
+ repo = GitRepository.containing(self.path)
59
+ except ConfigError as exc:
60
+ return self._fail(str(exc), ExitCode.USAGE)
61
+ except GitUnavailable as exc:
62
+ return self._fail(str(exc), ExitCode.USAGE)
63
+ if repo is None:
64
+ return self._fail(
65
+ f"{self.path} is not inside a git repository", ExitCode.USAGE
66
+ )
67
+ if self.depth < 1:
68
+ return self._fail("--depth must be 1 or more", ExitCode.USAGE)
69
+ layout = OutputLayout(self.output_root or repo.root, config.output_dir)
70
+ try:
71
+ refs = RefRange.parse(self.refs, repo)
72
+ analyzer = ChangeAnalyzer(
73
+ repo,
74
+ self.path,
75
+ exclude=list(config.exclude or [])
76
+ + [layout.relative_name, *LEGACY_OUTPUT_PATHS],
77
+ depth=self.depth,
78
+ compare_base=self.compare_base,
79
+ findings=self.findings,
80
+ caution=config.caution_settings(),
81
+ history=config.history_settings(), # a remote clone is complete enough
82
+ risk=config.risk_settings(),
83
+ )
84
+ report = analyzer.analyze(refs)
85
+ except RefError as exc:
86
+ return self._fail(str(exc), ExitCode.USAGE)
87
+ except GitError as exc:
88
+ return self._fail(str(exc), ExitCode.ERROR)
89
+
90
+ markdown = MarkdownRenderer(Footer(config.footer)).render(report)
91
+ if self.write:
92
+ self._write(layout, markdown, report.to_dict())
93
+ self._print(report, markdown)
94
+ return ExitCode.OK
95
+
96
+ def _write(self, layout: OutputLayout, markdown: str, data: Dict[str, Any]) -> None:
97
+ """Save changes.md and changes.json in the output folder."""
98
+ layout.prepare()
99
+ os.makedirs(layout.changes_dir, exist_ok=True)
100
+ with open(layout.changes_md, "w", encoding="utf-8") as f:
101
+ f.write(markdown)
102
+ with open(layout.changes_json, "w", encoding="utf-8") as f:
103
+ json.dump(data, f, indent=2)
104
+ f.write("\n")
105
+ print(f"Report written to {layout.changes_md}", file=sys.stderr)
106
+
107
+ def _print(self, report: ChangeReport, markdown: str) -> None:
108
+ """Show the report in the requested format on stdout."""
109
+ if self.output_format == "markdown":
110
+ print(markdown, end="")
111
+ elif self.output_format == "json":
112
+ print(json.dumps(report.to_dict(), indent=2))
113
+ else:
114
+ print(TextRenderer().render(report))
115
+
116
+ @staticmethod
117
+ def _fail(message: str, code: int) -> int:
118
+ print(f"gnost: {message}", file=sys.stderr)
119
+ return int(code)
120
+
121
+
122
+ def run(
123
+ path: str,
124
+ refs: str,
125
+ depth: int = DEFAULT_DEPTH,
126
+ output_format: str = "text",
127
+ findings: bool = False,
128
+ compare_base: bool = True,
129
+ write: bool = True,
130
+ output_root: Optional[str] = None,
131
+ remote: bool = False,
132
+ ) -> int:
133
+ """Entry point used by the CLI."""
134
+ return ChangesCommand(
135
+ path,
136
+ refs,
137
+ depth,
138
+ output_format,
139
+ findings,
140
+ compare_base,
141
+ write,
142
+ output_root,
143
+ remote,
144
+ ).run()
@@ -0,0 +1,192 @@
1
+ """`gnost init`: write a complete `.gnost.toml`, and optionally wire GNOST into the build.
2
+
3
+ `ConfigTemplate` builds the default settings file from the code's own defaults, and
4
+ `InitCommand` writes it and applies the selected integrations from the registry.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import sys
11
+ from typing import Iterable, List, Optional, Sequence
12
+
13
+ from gnost import __version__
14
+ from gnost.cli.commands.onboard import resolve_repo_root
15
+ from gnost.config.settings import ANALYZE_MAX_FINDINGS, ANALYZE_TIMEOUT, CONFIG_NAME
16
+ from gnost.core.caution import DEFAULT_RANGES, DEFAULT_WEIGHTS, CautionSettings
17
+ from gnost.core.risk import RiskSettings
18
+ from gnost.reporters.mermaid import DEFAULT_MAX_EDGES
19
+ from gnost.utils.integrations import (
20
+ Integration,
21
+ IntegrationError,
22
+ IntegrationResult,
23
+ default_integrations,
24
+ )
25
+ from gnost.utils.layout import DEFAULT_OUTPUT_DIR
26
+ from gnost.vcs.history import HistorySettings
27
+
28
+
29
+ class ConfigTemplate:
30
+ """The text of a `.gnost.toml` with every setting at its default and a comment on each."""
31
+
32
+ def render(self) -> str:
33
+ """The whole file."""
34
+ caution, history, risk = CautionSettings(), HistorySettings(), RiskSettings()
35
+ weights = "\n".join(f"{k} = {self._num(v)}" for k, v in DEFAULT_WEIGHTS.items())
36
+ ranges = "\n".join(
37
+ f"{k} = [{self._num(a)}, {self._num(b)}]"
38
+ for k, (a, b) in DEFAULT_RANGES.items()
39
+ )
40
+ authors = ", ".join(f'"{a}"' for a in history.exclude_authors)
41
+ return f"""# GNOST settings for this project. Every line is optional; the values shown are the
42
+ # defaults, so you only need to keep what you change. Lines starting with # are examples.
43
+ # Precedence: command-line flags, then this file, then the defaults.
44
+ # Full guide: https://gnost.readthedocs.io/en/stable/configuration.html
45
+
46
+ # Files and folders skipped by onboard and analyze. A name matches a folder anywhere;
47
+ # a pattern matches file names or paths, for example ["legacy", "*.generated.ts", "docs/build"].
48
+ exclude = []
49
+
50
+ # The folder GNOST writes its files to, inside the project.
51
+ output_dir = "{DEFAULT_OUTPUT_DIR}"
52
+
53
+ # Say so when a newer gnost exists (`gnost --version`; only in a terminal, never in CI).
54
+ check_updates = true
55
+
56
+ # End the Markdown files GNOST writes with a "Generated by GNOST" line.
57
+ footer = true
58
+
59
+ [onboard]
60
+ max_edges = {DEFAULT_MAX_EDGES} # largest diagram drawn file by file; bigger ones are grouped by folder
61
+ # collapse = 1 # always group diagrams by folder, this many levels deep
62
+ # depth = 3 # limit how deep the execution flow goes
63
+
64
+ [caution] # which files are "risky to change"
65
+ threshold = {self._num(caution.threshold)} # lowest caution score reported, 0 to 100
66
+ limit = {caution.limit} # most files reported
67
+
68
+ [caution.weights] # the most each signal can add to a score, 0 to 1
69
+ {weights}
70
+
71
+ [caution.ranges] # [value that counts as 0, value that counts as 1]
72
+ {ranges}
73
+
74
+ [risk] # files that are fragile to change AND changing often (needs git history)
75
+ threshold = {self._num(risk.threshold)} # lowest risk listed, 0 to 100
76
+ limit = {risk.limit} # most files listed
77
+ churn_weight = {self._num(risk.churn_weight)} # 1 = risk is caution x change activity; 0 = ignore change activity
78
+
79
+ [history] # change hotspots: how often files change (needs git and its history)
80
+ enabled = {str(history.enabled).lower()}
81
+ days = {history.days} # how far back to look
82
+ max_commits = {history.max_commits} # most commits read
83
+ recent_days = {history.recent_days} # what counts as "recent" in the hotspot table
84
+ min_commits = {history.min_commits} # a file needs this many changes to be listed
85
+ top = {history.top} # most files listed in ONBOARD.md
86
+ max_files_per_commit = {history.max_files_per_commit} # bigger commits (mass reformat, vendoring) are ignored
87
+ exclude_authors = [{authors}] # patterns; bots do not count as people
88
+
89
+ [analyze]
90
+ # analyzers = ["maintainability", "readability"] # default: all of them
91
+ # fail_under = 7.5 # CI: exit with code 3 when the final score (0 to 10) is lower
92
+ # baseline = ".gnost/baseline.json" # report only findings that are not in this file
93
+ timeout = {ANALYZE_TIMEOUT} # seconds each analyzer may run
94
+ max_findings = {ANALYZE_MAX_FINDINGS} # most findings kept per analyzer
95
+ parallel = false # run the analyzers at the same time
96
+ """
97
+
98
+ @staticmethod
99
+ def _num(value: float) -> str:
100
+ """A number as TOML text: 40 rather than 40.0."""
101
+ return str(int(value)) if float(value).is_integer() else str(value)
102
+
103
+
104
+ def default_config_text() -> str:
105
+ """The default `.gnost.toml` text (what `gnost init --print` shows)."""
106
+ return ConfigTemplate().render()
107
+
108
+
109
+ class InitCommand:
110
+ """Writes the config file and applies the chosen integrations under one project root."""
111
+
112
+ def __init__(
113
+ self,
114
+ root: str,
115
+ integrations: Sequence[Integration],
116
+ force: bool = False,
117
+ dry_run: bool = False,
118
+ ) -> None:
119
+ self.root = root
120
+ self.integrations = integrations
121
+ self.force = force
122
+ self.dry_run = dry_run
123
+
124
+ @classmethod
125
+ def available(cls) -> Sequence[Integration]:
126
+ """Every integration `init` offers (the CLI builds its flags from this)."""
127
+ return default_integrations(__version__)
128
+
129
+ def run(self) -> int:
130
+ """Do the work and print what happened. Returns the exit code."""
131
+ print(f"GNOST init in {self.root}")
132
+ status = self._write_config()
133
+ try:
134
+ for integration in self.integrations:
135
+ self._report(integration.apply(self.root, self.dry_run, self.force))
136
+ except IntegrationError as exc:
137
+ print(f"gnost: {exc}", file=sys.stderr)
138
+ return 2
139
+ if not self.dry_run and status == 0:
140
+ print("\nNext: gnost onboard .")
141
+ return status
142
+
143
+ def _write_config(self) -> int:
144
+ """Write .gnost.toml unless it exists (without force). Returns 1 if it was refused alone."""
145
+ path = os.path.join(self.root, CONFIG_NAME)
146
+ if os.path.exists(path) and not self.force:
147
+ print(
148
+ f" {CONFIG_NAME}: already exists (use --force to overwrite, --print to see the defaults)"
149
+ )
150
+ return 0 if self.integrations else 1
151
+ if self.dry_run:
152
+ print(f" {CONFIG_NAME}: would write {path}")
153
+ return 0
154
+ with open(path, "w", encoding="utf-8") as f:
155
+ f.write(default_config_text())
156
+ print(
157
+ f" {CONFIG_NAME}: written, with every setting at its default; edit what you need"
158
+ )
159
+ return 0
160
+
161
+ @staticmethod
162
+ def _report(result: IntegrationResult) -> None:
163
+ """Print one integration's outcome and its diff."""
164
+ messages = {
165
+ "unchanged": "already set up, nothing to do",
166
+ "exists": "already exists (use --force to overwrite)",
167
+ "created": f"written {result.path}",
168
+ "would create": f"would write {result.path}",
169
+ "changed": f"updated {result.path}",
170
+ "would change": f"would change {result.path}",
171
+ }
172
+ print(f" {result.label}: {messages[result.status]}")
173
+ for line in result.diff:
174
+ print(f" {line}")
175
+
176
+
177
+ def run(
178
+ path: Optional[str] = None,
179
+ selected: Iterable[str] = (),
180
+ force: bool = False,
181
+ print_only: bool = False,
182
+ dry_run: bool = False,
183
+ ) -> int:
184
+ """Entry point for `gnost init`: `selected` holds the integration flags that were given."""
185
+ if print_only:
186
+ print(default_config_text(), end="")
187
+ return 0
188
+ chosen: List[Integration] = [
189
+ i for i in InitCommand.available() if i.flag in set(selected)
190
+ ]
191
+ root = resolve_repo_root(os.path.abspath(path or "."))
192
+ return InitCommand(root, chosen, force=force, dry_run=dry_run).run()
@@ -16,6 +16,7 @@ from gnost.core.callgraph import build_call_graph, find_flows
16
16
  from gnost.core.caution import CautionSettings
17
17
  from gnost.core.resolver import ImportResolver
18
18
  from gnost.core.insight_builder import InsightBuilder
19
+ from gnost.core.risk import RiskCalculator, RiskSettings
19
20
  from gnost.core.graph import DependencyGraph
20
21
  from gnost.core.flow import FlowBuilder
21
22
  from gnost.reporters.summary import SummaryReporter
@@ -27,7 +28,10 @@ from gnost.reporters.mermaid import (
27
28
  )
28
29
  from gnost.reporters.readme import ReadmeInjector
29
30
  from gnost.reporters.insights_json import build_payload, write_payload
31
+ from gnost.utils.footer import Footer
32
+ from gnost.utils.layout import LEGACY_OUTPUT_PATHS, OutputLayout
30
33
  from gnost.utils.progress import progress_bar
34
+ from gnost.vcs.history import HistoryReader, HistorySettings
31
35
 
32
36
 
33
37
  def resolve_repo_root(path: str) -> str:
@@ -136,24 +140,34 @@ def run(
136
140
  collapse: Optional[int] = None,
137
141
  exclude: Optional[list] = None,
138
142
  caution: Optional[CautionSettings] = None,
139
- ):
140
- """
141
- gnost onboard [path] [--mermaid] [--json [FILE]] [--insights-only]
142
- Generates a high-level onboarding summary for a codebase.
143
-
144
- `json_out` writes the insights as JSON: "" means the default path
145
- (docs/insights/gnost_insights.json), anything else is the file to write.
146
- `insights_only` writes only that JSON, skipping ONBOARD.md and the diagrams.
143
+ output_dir: Optional[str] = None,
144
+ html: bool = True,
145
+ history: Optional[HistorySettings] = None,
146
+ risk: Optional[RiskSettings] = None,
147
+ output_root: Optional[str] = None,
148
+ source: Optional[str] = None,
149
+ footer: bool = True,
150
+ ) -> None:
151
+ """Onboard a codebase: write the guide, diagrams, insights JSON and explorer page.
152
+
153
+ Everything goes into the output folder (`.gnost/`, see OutputLayout). `diagram_only` writes only the diagram.
147
154
  """
148
155
  scan_root = os.path.abspath(path or ".")
149
- output_root = resolve_repo_root(scan_root)
150
- docs_dir = os.path.join(output_root, "docs")
151
- flow_dir = os.path.join(docs_dir, "flow")
156
+ # A remote clone passes output_root so the files land in the current folder.
157
+ output_root = output_root or resolve_repo_root(scan_root)
158
+ layout = OutputLayout(output_root, output_dir)
159
+ flow_dir = layout.flow_dir
152
160
  write_documents = not insights_only
153
161
  if insights_only and json_out is None:
154
162
  json_out = ""
163
+ stamp = Footer(footer)
164
+ first_run = not os.path.isdir(layout.folder)
165
+ # The scanners must never read GNOST's own output.
166
+ own_output = [layout.relative_name] + list(LEGACY_OUTPUT_PATHS)
167
+ exclude = list(exclude or []) + own_output
168
+ if json_out is not None or write_documents:
169
+ layout.prepare()
155
170
  if write_documents:
156
- os.makedirs(docs_dir, exist_ok=True)
157
171
  os.makedirs(flow_dir, exist_ok=True)
158
172
 
159
173
  with progress_bar(enabled=progress, total=4, desc="Onboarding") as bar:
@@ -173,6 +187,7 @@ def run(
173
187
  scanner = ScannerEngine(adapters=adapters, exclude=exclude)
174
188
  scan_result = scanner.scan(scan_root)
175
189
  scan_result.routes = find_routes(scan_result)
190
+ stamp = stamp.for_languages(scan_result.languages)
176
191
  # The line-count tables only understand plain folder names, not globs.
177
192
  loc_exclude = [p for p in (exclude or []) if not re.search(r"[*?\[/]", p)]
178
193
  loc_data = loc_scan(scan_root, exclude=loc_exclude)
@@ -213,13 +228,25 @@ def run(
213
228
  )
214
229
  insights = insight_builder.build()
215
230
 
231
+ # -------------------------
232
+ # 4.55 Change history (git), if there is any
233
+ # -------------------------
234
+ scanned = {
235
+ os.path.relpath(f.path, scan_root).replace(os.sep, "/")
236
+ for f in scan_result.files
237
+ }
238
+ changes = HistoryReader(history or HistorySettings()).analyze(
239
+ scan_root, scanned
240
+ )
241
+ risks = RiskCalculator(risk or RiskSettings()).report(
242
+ insight_builder.caution_scores, changes.hotspots, scan_root
243
+ )
244
+
216
245
  # -------------------------
217
246
  # 4.6 Insights JSON (optional)
218
247
  # -------------------------
219
- if json_out is not None:
220
- json_path = json_out or os.path.join(
221
- docs_dir, "insights", "gnost_insights.json"
222
- )
248
+ if json_out is not None or not diagram_only:
249
+ json_path = json_out or layout.insights_json
223
250
  payload = build_payload(
224
251
  scan_result,
225
252
  flow_result,
@@ -227,6 +254,8 @@ def run(
227
254
  insights,
228
255
  flows=function_flows,
229
256
  call_graph=call_graph,
257
+ changes=changes,
258
+ risks=risks,
230
259
  )
231
260
  write_payload(payload, json_path)
232
261
  print(f"Insights JSON written to {json_path}")
@@ -300,19 +329,25 @@ def run(
300
329
 
301
330
  with open(os.path.join(flow_dir, "FLOW-full.md"), "w", encoding="utf-8") as f:
302
331
  f.write(
303
- "# Full Execution Flow\n\n" + full_md + "\n\n"
304
- "> ℹ️ This file renders the complete Mermaid diagram on GitHub.\n"
305
- "> For raw Mermaid source, see "
306
- "[**FLOW-full.mmd**](./FLOW-full.mmd). Every file and import, "
307
- "ungrouped and nothing omitted: "
308
- "[**flow-complete.mmd**](./flow-complete.mmd)\n"
332
+ stamp.append(
333
+ "# Full Execution Flow\n\n" + full_md + "\n\n"
334
+ "> ℹ️ This file renders the complete Mermaid diagram on GitHub.\n"
335
+ "> For raw Mermaid source, see "
336
+ "[**FLOW-full.mmd**](./FLOW-full.mmd). Every file and import, "
337
+ "ungrouped and nothing omitted: "
338
+ "[**flow-complete.mmd**](./flow-complete.mmd)\n"
339
+ )
309
340
  )
310
341
 
311
342
  if function_flows:
312
343
  with open(
313
344
  os.path.join(flow_dir, "function-flow.md"), "w", encoding="utf-8"
314
345
  ) as f:
315
- f.write(render_function_flows(function_flows, scan_result.root))
346
+ f.write(
347
+ stamp.append(
348
+ render_function_flows(function_flows, scan_result.root)
349
+ )
350
+ )
316
351
 
317
352
  # Overview diagram (optional standalone file)
318
353
  overview_diagram = MermaidFlowReporter(
@@ -370,7 +405,7 @@ def run(
370
405
  lines.append(f"**Execution chain:** {chain}\n")
371
406
 
372
407
  with open(os.path.join(flow_dir, "entry-paths.md"), "w", encoding="utf-8") as f:
373
- f.write("\n".join(lines))
408
+ f.write(stamp.append("\n".join(lines)))
374
409
 
375
410
  # -------------------------
376
411
  # 5.7 Keyword-based paths
@@ -468,7 +503,7 @@ def run(
468
503
  with open(
469
504
  os.path.join(flow_dir, "folder-paths.md"), "w", encoding="utf-8"
470
505
  ) as f:
471
- f.write("\n".join(lines))
506
+ f.write(stamp.append("\n".join(lines)))
472
507
 
473
508
  # -------------------------
474
509
  # 6. Normal onboarding
@@ -478,13 +513,16 @@ def run(
478
513
  flow=flow_result,
479
514
  graph=graph,
480
515
  insights=insights,
516
+ changes=changes,
517
+ risks=risks,
518
+ root_label=source,
481
519
  ).render()
482
520
 
483
521
  MarkdownReporter(
484
522
  scan=scan_result,
485
523
  flow=flow_result,
486
524
  output_file="ONBOARD.md",
487
- output_root=output_root,
525
+ output_root=layout.folder,
488
526
  loc_data=loc_data,
489
527
  mermaid_depth=depth,
490
528
  mermaid_layered=layered,
@@ -492,10 +530,22 @@ def run(
492
530
  mermaid_collapse=collapse,
493
531
  insights=insights,
494
532
  function_flows=function_flows,
533
+ changes=changes,
534
+ risks=risks,
535
+ root_label=source,
536
+ footer=stamp,
495
537
  ).write()
496
538
 
539
+ if html:
540
+ from gnost.cli.commands.show import build_page
541
+
542
+ with open(layout.flow_html, "w", encoding="utf-8") as f:
543
+ f.write(build_page(os.path.join(flow_dir, "flow-complete.mmd")))
544
+
497
545
  if inject:
498
- injector = ReadmeInjector(output_root)
546
+ injector = ReadmeInjector(
547
+ output_root, link=f"./{layout.relative_name}/ONBOARD.md"
548
+ )
499
549
  changed = injector.inject()
500
550
 
501
551
  if changed:
@@ -505,3 +555,10 @@ def run(
505
555
 
506
556
  if bar is not None:
507
557
  bar.update(1)
558
+
559
+ print(f"\nGNOST wrote its files to {layout.folder}")
560
+ print(f" Guide: {layout.relative_name}/ONBOARD.md")
561
+ if html:
562
+ print(" Open the explorer: gnost open flow")
563
+ if first_run and layout.has_legacy_output():
564
+ print(f"\nNote: {layout.moved_notice()}")
@@ -0,0 +1,53 @@
1
+ """Lets `onboard`, `analyze` and `changes` take a repository address instead of a folder.
2
+
3
+ `RemoteTarget` decides whether the path argument is an address and, if so, clones it with
4
+ `RemoteClone`. While the clone is in use the process is marked as reading untrusted code, so
5
+ the analyzers ignore the repository's own tool configuration.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import os
12
+ import sys
13
+ from contextlib import contextmanager
14
+ from typing import Iterator, Optional
15
+
16
+ from gnost.analysis.utils.tool_command import UNTRUSTED_ENV
17
+ from gnost.vcs.remote import RemoteClone, RemoteUrl
18
+
19
+ COMMANDS = ("onboard", "analyze", "changes")
20
+
21
+
22
+ class RemoteTarget:
23
+ """A repository address given where a folder is expected."""
24
+
25
+ def __init__(self, url: RemoteUrl, ref: Optional[str]) -> None:
26
+ self.url = url
27
+ self.ref = ref
28
+
29
+ @classmethod
30
+ def from_args(cls, args: argparse.Namespace) -> Optional["RemoteTarget"]:
31
+ """The target for this command line, or None when the path is a normal folder."""
32
+ path = getattr(args, "path", None)
33
+ if args.cmd not in COMMANDS or not path or not RemoteUrl.looks_remote(path):
34
+ return None
35
+ return cls(RemoteUrl.parse(path), getattr(args, "ref", None))
36
+
37
+ @contextmanager
38
+ def open(self) -> Iterator[str]:
39
+ """Clone, yield the local folder, then delete the clone and restore the environment."""
40
+ print(
41
+ f"Cloning {self.url.name} (read only, nothing in it is run)...",
42
+ file=sys.stderr,
43
+ )
44
+ before = os.environ.get(UNTRUSTED_ENV)
45
+ os.environ[UNTRUSTED_ENV] = "1"
46
+ try:
47
+ with RemoteClone(self.url, self.ref) as folder:
48
+ yield folder
49
+ finally:
50
+ if before is None:
51
+ os.environ.pop(UNTRUSTED_ENV, None)
52
+ else:
53
+ os.environ[UNTRUSTED_ENV] = before
@@ -21,6 +21,19 @@ GRAPH_EDGE_THRESHOLD = 150
21
21
  _ARROW = re.compile(r"^\s*\w+\s+(?:-->|==>|-\.->)", re.MULTILINE)
22
22
 
23
23
 
24
+ def build_page(path: str, mode: str = "auto") -> str:
25
+ """The self-contained HTML page for a .mmd or .md file."""
26
+ ext = os.path.splitext(path)[1].lower()
27
+ kind = "mermaid" if ext in _MERMAID_EXT else "markdown"
28
+ with open(path, encoding="utf-8") as f:
29
+ source = f.read()
30
+ if kind == "mermaid":
31
+ big = len(_ARROW.findall(source)) > GRAPH_EDGE_THRESHOLD
32
+ if mode == "graph" or (mode == "auto" and big):
33
+ kind = "graph"
34
+ return render_viewer_html(source, os.path.basename(path), kind) # type: ignore[arg-type]
35
+
36
+
24
37
  def run(
25
38
  path: str,
26
39
  output: Optional[str] = None,
@@ -39,25 +52,13 @@ def run(
39
52
  if open_browser and not webbrowser.open(pathlib.Path(path).resolve().as_uri()):
40
53
  print("Could not open a browser; open the file above manually.")
41
54
  return 0
42
- if ext in _MERMAID_EXT:
43
- kind = "mermaid"
44
- elif ext in _MARKDOWN_EXT:
45
- kind = "markdown"
46
- else:
55
+ if ext not in _MERMAID_EXT and ext not in _MARKDOWN_EXT:
47
56
  print(
48
57
  "gnost: supported files are .mmd, .mermaid, .md and .html", file=sys.stderr
49
58
  )
50
59
  return 2
51
60
 
52
- with open(path, encoding="utf-8") as f:
53
- source = f.read()
54
-
55
- if kind == "mermaid":
56
- big = len(_ARROW.findall(source)) > GRAPH_EDGE_THRESHOLD
57
- if mode == "graph" or (mode == "auto" and big):
58
- kind = "graph"
59
-
60
- html = render_viewer_html(source, os.path.basename(path), kind) # type: ignore[arg-type]
61
+ html = build_page(path, mode)
61
62
  if output is None:
62
63
  fd, output = tempfile.mkstemp(prefix="gnost-show-", suffix=".html")
63
64
  os.close(fd)
@@ -1,10 +1,25 @@
1
+ from typing import Dict
2
+
1
3
  LANGUAGES = {
2
4
  "py": {"name": "Python", "comment": "#"},
3
- "js": {"name": "JavaScript.js", "comment": "//"},
4
- "jsx": {"name": "JavaScript.jsx", "comment": "//"},
5
- "ts": {"name": "TypeScript.ts", "comment": "//"},
6
- "tsx": {"name": "TypeScript.tsx", "comment": "//"},
5
+ "js": {"name": "JavaScript", "comment": "//"},
6
+ "jsx": {"name": "JavaScript", "comment": "//"},
7
+ "ts": {"name": "TypeScript", "comment": "//"},
8
+ "tsx": {"name": "TypeScript", "comment": "//"},
7
9
  "java": {"name": "Java", "comment": "//"},
8
10
  "c": {"name": "C", "comment": "//"},
9
11
  "cpp": {"name": "C++", "comment": "//"},
10
12
  }
13
+
14
+
15
+ def by_language_name(
16
+ by_extension: Dict[str, Dict[str, int]],
17
+ ) -> Dict[str, Dict[str, int]]:
18
+ """Merge per-extension counts into one entry per language (js and jsx are JavaScript)."""
19
+ merged = {}
20
+ for ext, stats in by_extension.items():
21
+ name = LANGUAGES.get(ext, {}).get("name", ext.upper())
22
+ into = merged.setdefault(name, {key: 0 for key in stats})
23
+ for key, value in stats.items():
24
+ into[key] = into.get(key, 0) + value
25
+ return merged