@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
@@ -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:
@@ -213,13 +227,25 @@ def run(
213
227
  )
214
228
  insights = insight_builder.build()
215
229
 
230
+ # -------------------------
231
+ # 4.55 Change history (git), if there is any
232
+ # -------------------------
233
+ scanned = {
234
+ os.path.relpath(f.path, scan_root).replace(os.sep, "/")
235
+ for f in scan_result.files
236
+ }
237
+ changes = HistoryReader(history or HistorySettings()).analyze(
238
+ scan_root, scanned
239
+ )
240
+ risks = RiskCalculator(risk or RiskSettings()).report(
241
+ insight_builder.caution_scores, changes.hotspots, scan_root
242
+ )
243
+
216
244
  # -------------------------
217
245
  # 4.6 Insights JSON (optional)
218
246
  # -------------------------
219
- if json_out is not None:
220
- json_path = json_out or os.path.join(
221
- docs_dir, "insights", "gnost_insights.json"
222
- )
247
+ if json_out is not None or not diagram_only:
248
+ json_path = json_out or layout.insights_json
223
249
  payload = build_payload(
224
250
  scan_result,
225
251
  flow_result,
@@ -227,6 +253,8 @@ def run(
227
253
  insights,
228
254
  flows=function_flows,
229
255
  call_graph=call_graph,
256
+ changes=changes,
257
+ risks=risks,
230
258
  )
231
259
  write_payload(payload, json_path)
232
260
  print(f"Insights JSON written to {json_path}")
@@ -300,19 +328,25 @@ def run(
300
328
 
301
329
  with open(os.path.join(flow_dir, "FLOW-full.md"), "w", encoding="utf-8") as f:
302
330
  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"
331
+ stamp.append(
332
+ "# Full Execution Flow\n\n" + full_md + "\n\n"
333
+ "> ℹ️ This file renders the complete Mermaid diagram on GitHub.\n"
334
+ "> For raw Mermaid source, see "
335
+ "[**FLOW-full.mmd**](./FLOW-full.mmd). Every file and import, "
336
+ "ungrouped and nothing omitted: "
337
+ "[**flow-complete.mmd**](./flow-complete.mmd)\n"
338
+ )
309
339
  )
310
340
 
311
341
  if function_flows:
312
342
  with open(
313
343
  os.path.join(flow_dir, "function-flow.md"), "w", encoding="utf-8"
314
344
  ) as f:
315
- f.write(render_function_flows(function_flows, scan_result.root))
345
+ f.write(
346
+ stamp.append(
347
+ render_function_flows(function_flows, scan_result.root)
348
+ )
349
+ )
316
350
 
317
351
  # Overview diagram (optional standalone file)
318
352
  overview_diagram = MermaidFlowReporter(
@@ -370,7 +404,7 @@ def run(
370
404
  lines.append(f"**Execution chain:** {chain}\n")
371
405
 
372
406
  with open(os.path.join(flow_dir, "entry-paths.md"), "w", encoding="utf-8") as f:
373
- f.write("\n".join(lines))
407
+ f.write(stamp.append("\n".join(lines)))
374
408
 
375
409
  # -------------------------
376
410
  # 5.7 Keyword-based paths
@@ -468,7 +502,7 @@ def run(
468
502
  with open(
469
503
  os.path.join(flow_dir, "folder-paths.md"), "w", encoding="utf-8"
470
504
  ) as f:
471
- f.write("\n".join(lines))
505
+ f.write(stamp.append("\n".join(lines)))
472
506
 
473
507
  # -------------------------
474
508
  # 6. Normal onboarding
@@ -478,13 +512,16 @@ def run(
478
512
  flow=flow_result,
479
513
  graph=graph,
480
514
  insights=insights,
515
+ changes=changes,
516
+ risks=risks,
517
+ root_label=source,
481
518
  ).render()
482
519
 
483
520
  MarkdownReporter(
484
521
  scan=scan_result,
485
522
  flow=flow_result,
486
523
  output_file="ONBOARD.md",
487
- output_root=output_root,
524
+ output_root=layout.folder,
488
525
  loc_data=loc_data,
489
526
  mermaid_depth=depth,
490
527
  mermaid_layered=layered,
@@ -492,10 +529,22 @@ def run(
492
529
  mermaid_collapse=collapse,
493
530
  insights=insights,
494
531
  function_flows=function_flows,
532
+ changes=changes,
533
+ risks=risks,
534
+ root_label=source,
535
+ footer=stamp,
495
536
  ).write()
496
537
 
538
+ if html:
539
+ from gnost.cli.commands.show import build_page
540
+
541
+ with open(layout.flow_html, "w", encoding="utf-8") as f:
542
+ f.write(build_page(os.path.join(flow_dir, "flow-complete.mmd")))
543
+
497
544
  if inject:
498
- injector = ReadmeInjector(output_root)
545
+ injector = ReadmeInjector(
546
+ output_root, link=f"./{layout.relative_name}/ONBOARD.md"
547
+ )
499
548
  changed = injector.inject()
500
549
 
501
550
  if changed:
@@ -505,3 +554,10 @@ def run(
505
554
 
506
555
  if bar is not None:
507
556
  bar.update(1)
557
+
558
+ print(f"\nGNOST wrote its files to {layout.folder}")
559
+ print(f" Guide: {layout.relative_name}/ONBOARD.md")
560
+ if html:
561
+ print(" Open the explorer: gnost open flow")
562
+ if first_run and layout.has_legacy_output():
563
+ 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