@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.
- package/bundle/_internal/base_library.zip +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.3.dist-info → gnost-0.6.0rc1.dist-info}/METADATA +7 -4
- package/bundle/_internal/{gnost-0.5.3.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/yaml/_yaml.cpython-312-darwin.so +0 -0
- package/bundle/gnost +0 -0
- package/package.json +1 -1
- /package/bundle/_internal/{gnost-0.5.3.dist-info/REQUESTED → certifi/py.typed} +0 -0
- /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/INSTALLER +0 -0
- /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/WHEEL +0 -0
- /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/direct_url.json +0 -0
- /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/entry_points.txt +0 -0
- /package/bundle/_internal/{gnost-0.5.3.dist-info → gnost-0.6.0rc1.dist-info}/licenses/LICENSE +0 -0
- /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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
|
150
|
-
|
|
151
|
-
|
|
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
|
|
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
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
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(
|
|
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=
|
|
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(
|
|
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
|
-
|
|
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
|
|
4
|
-
"jsx": {"name": "JavaScript
|
|
5
|
-
"ts": {"name": "TypeScript
|
|
6
|
-
"tsx": {"name": "TypeScript
|
|
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
|