@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,346 @@
|
|
|
1
|
+
"""Ways `gnost init` wires GNOST into a project: pom.xml, package.json, a GitHub workflow.
|
|
2
|
+
|
|
3
|
+
Each is an `Integration` subclass in the `INTEGRATIONS` registry; the command and its flags are
|
|
4
|
+
built from that list, so a new one (say Gradle) is one new class. Edits are small text insertions
|
|
5
|
+
that keep the user's comments and formatting, and are skipped when already set up.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import difflib
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import re
|
|
14
|
+
import xml.etree.ElementTree as ET
|
|
15
|
+
from abc import ABC, abstractmethod
|
|
16
|
+
from dataclasses import dataclass, field
|
|
17
|
+
from typing import List, Optional, Tuple
|
|
18
|
+
|
|
19
|
+
from gnost.utils.layout import DEFAULT_OUTPUT_DIR
|
|
20
|
+
|
|
21
|
+
# Version of the Maven plugin that exists on Central; the release updates it when Maven is published.
|
|
22
|
+
MAVEN_PLUGIN_VERSION = "0.5.3"
|
|
23
|
+
MAVEN_GROUP = "io.github.mohdzain98"
|
|
24
|
+
MAVEN_ARTIFACT = "gnost-maven-plugin"
|
|
25
|
+
NPM_SCRIPT_NAME = "gnost"
|
|
26
|
+
NPM_SCRIPT = "npx --yes gnost-cli onboard ."
|
|
27
|
+
WORKFLOW_PATH = ".github/workflows/gnost.yml"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class IntegrationError(Exception):
|
|
31
|
+
"""The file cannot be edited safely; the message says why and what to do."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass
|
|
35
|
+
class IntegrationResult:
|
|
36
|
+
"""What one integration did (or would do in a dry run)."""
|
|
37
|
+
|
|
38
|
+
label: str
|
|
39
|
+
status: str # "changed", "would change", "unchanged", "exists", "created", "would create"
|
|
40
|
+
path: str
|
|
41
|
+
diff: List[str] = field(default_factory=list)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
# ------------------------------------------------------------------ pom.xml
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class PomDocument:
|
|
48
|
+
"""A pom.xml as text, with enough structure to insert a plugin without reformatting it."""
|
|
49
|
+
|
|
50
|
+
_TAG = re.compile(
|
|
51
|
+
r"<!--.*?-->|<!\[CDATA\[.*?\]\]>|<\?.*?\?>|<!DOCTYPE[^>]*>"
|
|
52
|
+
r"|<(/?)([A-Za-z_][\w.\-:]*)([^>]*?)(/?)>",
|
|
53
|
+
re.DOTALL,
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
def __init__(self, text: str) -> None:
|
|
57
|
+
self.text = text
|
|
58
|
+
self.eol = "\r\n" if "\r\n" in text else "\n"
|
|
59
|
+
self.unit = self._indent_unit()
|
|
60
|
+
self._tags = self._scan()
|
|
61
|
+
|
|
62
|
+
def with_plugin(self, group: str, artifact: str, version: str) -> Optional[str]:
|
|
63
|
+
"""The text with the plugin added under build/plugins, or None if it is already there."""
|
|
64
|
+
if artifact in self.text:
|
|
65
|
+
return None
|
|
66
|
+
if self._find("open", ("project",)) is None:
|
|
67
|
+
raise IntegrationError("pom.xml has no <project> element")
|
|
68
|
+
plugins = self._find("close", ("project", "build", "plugins"))
|
|
69
|
+
build = self._find("close", ("project", "build"))
|
|
70
|
+
project = self._find("close", ("project",))
|
|
71
|
+
plugin = lambda indent: self._plugin(group, artifact, version, indent) # noqa: E731
|
|
72
|
+
if plugins is not None:
|
|
73
|
+
base = self._indent_of(plugins) + self.unit
|
|
74
|
+
insertion, at = plugin(base) + self.eol, self._line_start(plugins)
|
|
75
|
+
elif build is not None:
|
|
76
|
+
inner = self._indent_of(build) + self.unit
|
|
77
|
+
insertion = self._wrap("plugins", inner, plugin(inner + self.unit))
|
|
78
|
+
at = self._line_start(build)
|
|
79
|
+
elif project is not None:
|
|
80
|
+
inner = self.unit
|
|
81
|
+
build_body = self._wrap(
|
|
82
|
+
"plugins", inner + self.unit, plugin(inner + self.unit * 2)
|
|
83
|
+
)
|
|
84
|
+
insertion = self._wrap("build", inner, build_body.rstrip("\r\n"))
|
|
85
|
+
at = self._line_start(project)
|
|
86
|
+
else:
|
|
87
|
+
raise IntegrationError("pom.xml is not complete (no closing </project>)")
|
|
88
|
+
edited = self.text[:at] + insertion + self.text[at:]
|
|
89
|
+
try:
|
|
90
|
+
ET.fromstring(edited.encode("utf-8"))
|
|
91
|
+
except ET.ParseError as exc: # never write a file we broke
|
|
92
|
+
raise IntegrationError(
|
|
93
|
+
f"the edited pom.xml would not be valid XML ({exc})"
|
|
94
|
+
) from exc
|
|
95
|
+
return edited
|
|
96
|
+
|
|
97
|
+
def _plugin(self, group: str, artifact: str, version: str, indent: str) -> str:
|
|
98
|
+
"""The <plugin> block, each line starting with indent."""
|
|
99
|
+
lines = [
|
|
100
|
+
"<plugin>",
|
|
101
|
+
f"{self.unit}<groupId>{group}</groupId>",
|
|
102
|
+
f"{self.unit}<artifactId>{artifact}</artifactId>",
|
|
103
|
+
f"{self.unit}<version>{version}</version>",
|
|
104
|
+
"</plugin>",
|
|
105
|
+
]
|
|
106
|
+
return self.eol.join(indent + line for line in lines)
|
|
107
|
+
|
|
108
|
+
def _wrap(self, tag: str, indent: str, body: str) -> str:
|
|
109
|
+
"""body inside <tag>...</tag> at the given indentation, ending with a line break."""
|
|
110
|
+
return f"{indent}<{tag}>{self.eol}{body}{self.eol}{indent}</{tag}>{self.eol}"
|
|
111
|
+
|
|
112
|
+
def _scan(self) -> List[Tuple[str, Tuple[str, ...], int]]:
|
|
113
|
+
"""(kind, element path, start) for each tag; comments and CDATA are skipped."""
|
|
114
|
+
stack: List[str] = []
|
|
115
|
+
found: List[Tuple[str, Tuple[str, ...], int]] = []
|
|
116
|
+
for m in self._TAG.finditer(self.text):
|
|
117
|
+
if m.group(2) is None:
|
|
118
|
+
continue
|
|
119
|
+
name = m.group(2).split(":")[-1]
|
|
120
|
+
if m.group(4):
|
|
121
|
+
found.append(("empty", tuple(stack) + (name,), m.start()))
|
|
122
|
+
elif m.group(1):
|
|
123
|
+
if stack and stack[-1] == name:
|
|
124
|
+
found.append(("close", tuple(stack), m.start()))
|
|
125
|
+
stack.pop()
|
|
126
|
+
else:
|
|
127
|
+
stack.append(name)
|
|
128
|
+
found.append(("open", tuple(stack), m.start()))
|
|
129
|
+
return found
|
|
130
|
+
|
|
131
|
+
def _find(self, kind: str, path: Tuple[str, ...]) -> Optional[int]:
|
|
132
|
+
"""Start of the first tag of this kind at this element path, or None."""
|
|
133
|
+
return next(
|
|
134
|
+
(start for k, p, start in self._tags if k == kind and p == path), None
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
def _line_start(self, pos: int) -> int:
|
|
138
|
+
"""Index of the start of the line containing pos."""
|
|
139
|
+
return self.text.rfind("\n", 0, pos) + 1
|
|
140
|
+
|
|
141
|
+
def _indent_of(self, pos: int) -> str:
|
|
142
|
+
"""Leading whitespace of the line containing pos."""
|
|
143
|
+
line = self.text[self._line_start(pos) :]
|
|
144
|
+
return re.match(r"[ \t]*", line).group(0) # type: ignore[union-attr]
|
|
145
|
+
|
|
146
|
+
def _indent_unit(self) -> str:
|
|
147
|
+
"""The indentation step the file uses (its first indented element)."""
|
|
148
|
+
m = re.search(r"\n([ \t]+)<(?!/|!)", self.text)
|
|
149
|
+
return m.group(1) if m else " "
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
# ------------------------------------------------------------- integrations
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class Integration(ABC):
|
|
156
|
+
"""One thing `gnost init` can set up. Subclasses name the file and say how to change it."""
|
|
157
|
+
|
|
158
|
+
flag: str # command-line flag, without the dashes
|
|
159
|
+
help: str
|
|
160
|
+
label: str
|
|
161
|
+
relative_path: str
|
|
162
|
+
|
|
163
|
+
def apply(self, root: str, dry_run: bool, force: bool) -> IntegrationResult:
|
|
164
|
+
"""Set this up under root (or only describe it in a dry run)."""
|
|
165
|
+
path = os.path.join(root, self.relative_path)
|
|
166
|
+
return self._apply_to(path, dry_run, force)
|
|
167
|
+
|
|
168
|
+
@abstractmethod
|
|
169
|
+
def _apply_to(self, path: str, dry_run: bool, force: bool) -> IntegrationResult:
|
|
170
|
+
"""Do the work for the file at path."""
|
|
171
|
+
|
|
172
|
+
@staticmethod
|
|
173
|
+
def _diff(label: str, before: str, after: str) -> List[str]:
|
|
174
|
+
"""A unified diff of the change, one string per line."""
|
|
175
|
+
return list(
|
|
176
|
+
difflib.unified_diff(
|
|
177
|
+
before.splitlines(),
|
|
178
|
+
after.splitlines(),
|
|
179
|
+
f"{label} (before)",
|
|
180
|
+
f"{label} (after)",
|
|
181
|
+
lineterm="",
|
|
182
|
+
)
|
|
183
|
+
)
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
class EditsExistingFile(Integration):
|
|
187
|
+
"""An integration that changes a file the project already has."""
|
|
188
|
+
|
|
189
|
+
@abstractmethod
|
|
190
|
+
def edit(self, text: str) -> Optional[str]:
|
|
191
|
+
"""The new file text, or None when nothing needs to change."""
|
|
192
|
+
|
|
193
|
+
def _apply_to(self, path: str, dry_run: bool, force: bool) -> IntegrationResult:
|
|
194
|
+
"""Read the file, edit it, and write it back unless this is a dry run."""
|
|
195
|
+
if not os.path.isfile(path):
|
|
196
|
+
raise IntegrationError(f"no {self.relative_path} in the project folder")
|
|
197
|
+
with open(path, encoding="utf-8", newline="") as f:
|
|
198
|
+
before = f.read()
|
|
199
|
+
after = self.edit(before)
|
|
200
|
+
if after is None:
|
|
201
|
+
return IntegrationResult(self.label, "unchanged", path)
|
|
202
|
+
if not dry_run:
|
|
203
|
+
with open(path, "w", encoding="utf-8", newline="") as f:
|
|
204
|
+
f.write(after)
|
|
205
|
+
status = "would change" if dry_run else "changed"
|
|
206
|
+
return IntegrationResult(
|
|
207
|
+
self.label, status, path, self._diff(self.label, before, after)
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
class CreatesFile(Integration):
|
|
212
|
+
"""An integration that writes a new file and leaves an existing one alone unless forced."""
|
|
213
|
+
|
|
214
|
+
@abstractmethod
|
|
215
|
+
def content(self) -> str:
|
|
216
|
+
"""The text of the new file."""
|
|
217
|
+
|
|
218
|
+
def _apply_to(self, path: str, dry_run: bool, force: bool) -> IntegrationResult:
|
|
219
|
+
"""Write the file if it does not exist (or force is set)."""
|
|
220
|
+
if os.path.exists(path) and not force:
|
|
221
|
+
return IntegrationResult(self.label, "exists", path)
|
|
222
|
+
if dry_run:
|
|
223
|
+
return IntegrationResult(self.label, "would create", path)
|
|
224
|
+
os.makedirs(os.path.dirname(path), exist_ok=True)
|
|
225
|
+
with open(path, "w", encoding="utf-8") as f:
|
|
226
|
+
f.write(self.content())
|
|
227
|
+
return IntegrationResult(self.label, "created", path)
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
class PomIntegration(EditsExistingFile):
|
|
231
|
+
"""Adds gnost-maven-plugin to pom.xml."""
|
|
232
|
+
|
|
233
|
+
flag = "pom"
|
|
234
|
+
help = "Add gnost-maven-plugin to pom.xml"
|
|
235
|
+
label = "pom.xml"
|
|
236
|
+
relative_path = "pom.xml"
|
|
237
|
+
|
|
238
|
+
def edit(self, text: str) -> Optional[str]:
|
|
239
|
+
return PomDocument(text).with_plugin(
|
|
240
|
+
MAVEN_GROUP, MAVEN_ARTIFACT, MAVEN_PLUGIN_VERSION
|
|
241
|
+
)
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
class PackageJsonIntegration(EditsExistingFile):
|
|
245
|
+
"""Adds a "gnost" script to package.json, keeping its key order and indentation."""
|
|
246
|
+
|
|
247
|
+
flag = "npm"
|
|
248
|
+
help = 'Add a "gnost" script to package.json'
|
|
249
|
+
label = 'package.json ("gnost" script)'
|
|
250
|
+
relative_path = "package.json"
|
|
251
|
+
|
|
252
|
+
def edit(self, text: str) -> Optional[str]:
|
|
253
|
+
try:
|
|
254
|
+
data = json.loads(text)
|
|
255
|
+
except ValueError as exc:
|
|
256
|
+
raise IntegrationError(f"package.json is not valid JSON ({exc})") from exc
|
|
257
|
+
if not isinstance(data, dict):
|
|
258
|
+
raise IntegrationError("package.json is not a JSON object")
|
|
259
|
+
scripts = data.setdefault("scripts", {})
|
|
260
|
+
if not isinstance(scripts, dict):
|
|
261
|
+
raise IntegrationError('"scripts" in package.json is not an object')
|
|
262
|
+
if NPM_SCRIPT_NAME in scripts:
|
|
263
|
+
return None
|
|
264
|
+
scripts[NPM_SCRIPT_NAME] = NPM_SCRIPT
|
|
265
|
+
indent = (re.search(r"\n([ \t]+)\"", text) or [None, " "])[1]
|
|
266
|
+
return json.dumps(data, indent=indent, ensure_ascii=False) + (
|
|
267
|
+
"\n" if text.endswith("\n") else ""
|
|
268
|
+
)
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
class WorkflowIntegration(CreatesFile):
|
|
272
|
+
"""Writes a GitHub Actions workflow that runs the GNOST action on pull requests and pushes."""
|
|
273
|
+
|
|
274
|
+
flag = "github-action"
|
|
275
|
+
help = f"Write {WORKFLOW_PATH}"
|
|
276
|
+
label = "workflow"
|
|
277
|
+
relative_path = WORKFLOW_PATH
|
|
278
|
+
|
|
279
|
+
def __init__(self, version: str) -> None:
|
|
280
|
+
self.version = version
|
|
281
|
+
|
|
282
|
+
def content(self) -> str:
|
|
283
|
+
return f"""# Runs GNOST on every pull request and push: quality gate, onboarding guide and a pull
|
|
284
|
+
# request comment with what the change touches. Written by `gnost init --github-action`; edit freely.
|
|
285
|
+
name: GNOST
|
|
286
|
+
|
|
287
|
+
on:
|
|
288
|
+
pull_request:
|
|
289
|
+
push:
|
|
290
|
+
branches: [main]
|
|
291
|
+
|
|
292
|
+
permissions:
|
|
293
|
+
contents: read
|
|
294
|
+
pull-requests: write # for the pull request comment
|
|
295
|
+
# security-events: write # add this and set `sarif: "true"` to show findings in code scanning
|
|
296
|
+
|
|
297
|
+
jobs:
|
|
298
|
+
gnost:
|
|
299
|
+
runs-on: ubuntu-latest
|
|
300
|
+
steps:
|
|
301
|
+
- uses: actions/checkout@v4
|
|
302
|
+
with:
|
|
303
|
+
fetch-depth: 0 # full history: hotspots and `gnost changes` need it
|
|
304
|
+
- uses: mohdzain98/gnost@v{self.version}
|
|
305
|
+
with:
|
|
306
|
+
comment: "true" # one comment per pull request: blast radius, risk, new cycles
|
|
307
|
+
onboard: "true" # also attach the .gnost/ guide to the run
|
|
308
|
+
sarif: "false" # "true" uploads findings to code scanning
|
|
309
|
+
# fail-under: "7.5" # fail the job when the quality score is below this
|
|
310
|
+
"""
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
class AgentsIntegration(CreatesFile):
|
|
314
|
+
"""Writes AGENTS.md so coding agents find the GNOST files instead of re-reading everything."""
|
|
315
|
+
|
|
316
|
+
flag = "agents"
|
|
317
|
+
help = "Write AGENTS.md pointing coding agents to the .gnost/ folder"
|
|
318
|
+
label = "AGENTS.md"
|
|
319
|
+
relative_path = "AGENTS.md"
|
|
320
|
+
|
|
321
|
+
def __init__(self, folder: str = DEFAULT_OUTPUT_DIR) -> None:
|
|
322
|
+
self.folder = folder
|
|
323
|
+
|
|
324
|
+
def content(self) -> str:
|
|
325
|
+
return f"""# Notes for coding agents
|
|
326
|
+
|
|
327
|
+
This repository has a map of its own code, made by [GNOST](https://gnost.readthedocs.io).
|
|
328
|
+
Read it before you search the whole tree:
|
|
329
|
+
|
|
330
|
+
- `{self.folder}/ONBOARD.md`: entry points, how the code flows, routes, risky and often changed files.
|
|
331
|
+
- `{self.folder}/insights.json`: the same facts as data (files, imports, layers, cycles, routes, history).
|
|
332
|
+
- `{self.folder}/flow/`: Mermaid diagrams of how the files depend on each other.
|
|
333
|
+
|
|
334
|
+
Refresh it after large changes: `npx gnost-cli onboard .` (or `gnost onboard .`).
|
|
335
|
+
Before a change, `gnost changes origin/main` shows which files it reaches and how risky they are.
|
|
336
|
+
"""
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def default_integrations(gnost_version: str) -> Tuple[Integration, ...]:
|
|
340
|
+
"""The integrations `gnost init` offers; add a new class here to offer a new one."""
|
|
341
|
+
return (
|
|
342
|
+
PomIntegration(),
|
|
343
|
+
PackageJsonIntegration(),
|
|
344
|
+
WorkflowIntegration(gnost_version),
|
|
345
|
+
AgentsIntegration(),
|
|
346
|
+
)
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""Where GNOST writes its files: one folder (`.gnost/` by default) in the project.
|
|
2
|
+
|
|
3
|
+
`OutputLayout` knows every path inside that folder, the old pre-0.6.0 locations
|
|
4
|
+
(`ONBOARD.md`, `docs/...`) that are still read as a fallback, and how to create the folder
|
|
5
|
+
with its README and .gitignore. `output_dir` in `.gnost.toml` can name another folder.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
from typing import Optional
|
|
12
|
+
|
|
13
|
+
DEFAULT_OUTPUT_DIR = ".gnost"
|
|
14
|
+
# Old output places, skipped by the scanners so a run never reads its own output.
|
|
15
|
+
LEGACY_OUTPUT_PATHS = ("docs/flow", "docs/insights", "docs/analysis")
|
|
16
|
+
|
|
17
|
+
FOLDER_README = """# GNOST output
|
|
18
|
+
|
|
19
|
+
This folder was generated by [GNOST](https://gnost.readthedocs.io), a command line tool
|
|
20
|
+
that explains a codebase: where it starts, how it flows and which files matter.
|
|
21
|
+
|
|
22
|
+
| File | What it is |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `ONBOARD.md` | The onboarding guide: entry points, flow, hotspots, routes, risky files |
|
|
25
|
+
| `insights.json` | The same facts as data, for tools and AI (schema: `insights.schema.json`) |
|
|
26
|
+
| `flow/` | Mermaid diagrams (`.mmd`) and Markdown pages that GitHub renders |
|
|
27
|
+
| `flow.html` | The interactive flow explorer, one page that works offline (not committed) |
|
|
28
|
+
| `analysis/` | The code quality report from `gnost analyze -o` (`analysis.json`, `analysis.html`, `analysis.sarif`) |
|
|
29
|
+
| `changes/` | The report from `gnost changes BASE`: changed files, blast radius, risk (`changes.md`, `changes.json`) |
|
|
30
|
+
| `baseline.json` | Known findings, from `gnost analyze --write-baseline`, so CI can report only new ones |
|
|
31
|
+
|
|
32
|
+
It is safe to commit this folder. The `.html` pages are ignored (see `.gitignore` here)
|
|
33
|
+
because they are large and can be rebuilt.
|
|
34
|
+
|
|
35
|
+
Update it: `npx gnost-cli onboard .` or `gnost onboard .`. Open the explorer: `gnost open flow`.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
FOLDER_GITIGNORE = "# Large pages that GNOST rebuilds on demand.\n*.html\n"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class OutputLayout:
|
|
42
|
+
"""All output paths for one project root and the old places they replace.
|
|
43
|
+
|
|
44
|
+
Create it with the project root and the folder name from the config (default .gnost).
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
def __init__(self, root: str, dirname: Optional[str] = None) -> None:
|
|
48
|
+
self.root = os.path.abspath(root)
|
|
49
|
+
self.dirname = dirname or DEFAULT_OUTPUT_DIR
|
|
50
|
+
self.folder = (
|
|
51
|
+
self.dirname
|
|
52
|
+
if os.path.isabs(self.dirname)
|
|
53
|
+
else os.path.join(self.root, self.dirname)
|
|
54
|
+
)
|
|
55
|
+
self.onboard_md = os.path.join(self.folder, "ONBOARD.md")
|
|
56
|
+
self.insights_json = os.path.join(self.folder, "insights.json")
|
|
57
|
+
self.flow_dir = os.path.join(self.folder, "flow")
|
|
58
|
+
self.flow_html = os.path.join(self.folder, "flow.html")
|
|
59
|
+
self.analysis_dir = os.path.join(self.folder, "analysis")
|
|
60
|
+
self.analysis_json = os.path.join(self.analysis_dir, "analysis.json")
|
|
61
|
+
self.analysis_html = os.path.join(self.analysis_dir, "analysis.html")
|
|
62
|
+
self.analysis_sarif = os.path.join(self.analysis_dir, "analysis.sarif")
|
|
63
|
+
self.changes_dir = os.path.join(self.folder, "changes")
|
|
64
|
+
self.changes_md = os.path.join(self.changes_dir, "changes.md")
|
|
65
|
+
self.changes_json = os.path.join(self.changes_dir, "changes.json")
|
|
66
|
+
self.baseline_json = os.path.join(self.folder, "baseline.json")
|
|
67
|
+
|
|
68
|
+
# The places GNOST wrote to before 0.6.0.
|
|
69
|
+
@property
|
|
70
|
+
def legacy_onboard_md(self) -> str:
|
|
71
|
+
"""The old ONBOARD.md at the project root."""
|
|
72
|
+
return os.path.join(self.root, "ONBOARD.md")
|
|
73
|
+
|
|
74
|
+
@property
|
|
75
|
+
def legacy_flow_dir(self) -> str:
|
|
76
|
+
"""The old docs/flow folder."""
|
|
77
|
+
return os.path.join(self.root, "docs", "flow")
|
|
78
|
+
|
|
79
|
+
@property
|
|
80
|
+
def legacy_analysis_html(self) -> str:
|
|
81
|
+
"""The old docs/analysis/gnost_analysis.html report."""
|
|
82
|
+
return os.path.join(self.root, "docs", "analysis", "gnost_analysis.html")
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
def relative_name(self) -> str:
|
|
86
|
+
"""The folder as shown in messages and README links (forward slashes)."""
|
|
87
|
+
return self.dirname.replace(os.sep, "/")
|
|
88
|
+
|
|
89
|
+
def has_legacy_output(self) -> bool:
|
|
90
|
+
"""True if GNOST output from before 0.6.0 is present."""
|
|
91
|
+
return os.path.isfile(self.legacy_onboard_md) or os.path.isdir(
|
|
92
|
+
self.legacy_flow_dir
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
def prepare(self) -> None:
|
|
96
|
+
"""Create the folder with its README and .gitignore (an existing .gitignore is kept)."""
|
|
97
|
+
os.makedirs(self.folder, exist_ok=True)
|
|
98
|
+
with open(os.path.join(self.folder, "README.md"), "w", encoding="utf-8") as f:
|
|
99
|
+
f.write(FOLDER_README)
|
|
100
|
+
ignore = os.path.join(self.folder, ".gitignore")
|
|
101
|
+
if not os.path.exists(ignore):
|
|
102
|
+
with open(ignore, "w", encoding="utf-8") as f:
|
|
103
|
+
f.write(FOLDER_GITIGNORE)
|
|
104
|
+
|
|
105
|
+
def moved_notice(self) -> str:
|
|
106
|
+
"""One message about the 0.6.0 move, shown while old output is still being used."""
|
|
107
|
+
return (
|
|
108
|
+
f"GNOST now writes to {self.relative_name}/ (before 0.6.0: ONBOARD.md and docs/). "
|
|
109
|
+
"Your old files were left where they are; run `gnost onboard .` to create the "
|
|
110
|
+
"new folder, then delete the old files when you like."
|
|
111
|
+
)
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import threading
|
|
2
2
|
from contextlib import contextmanager
|
|
3
|
+
from typing import Any, Iterator, Optional
|
|
3
4
|
|
|
4
5
|
|
|
5
6
|
try:
|
|
@@ -13,8 +14,7 @@ _lock_ready = False
|
|
|
13
14
|
def _use_thread_lock() -> None:
|
|
14
15
|
"""Keep tqdm from creating a multiprocessing lock.
|
|
15
16
|
|
|
16
|
-
That lock starts
|
|
17
|
-
In the standalone binary that is gnost itself, and it fails on the arguments.
|
|
17
|
+
That lock starts a helper that relaunches sys.executable, which breaks the standalone binary.
|
|
18
18
|
"""
|
|
19
19
|
global _lock_ready
|
|
20
20
|
if not _lock_ready:
|
|
@@ -23,7 +23,10 @@ def _use_thread_lock() -> None:
|
|
|
23
23
|
|
|
24
24
|
|
|
25
25
|
@contextmanager
|
|
26
|
-
def progress_bar(
|
|
26
|
+
def progress_bar(
|
|
27
|
+
enabled: bool = False, total: Optional[int] = None, desc: Optional[str] = None
|
|
28
|
+
) -> Iterator[Any]:
|
|
29
|
+
"""Yield a tqdm progress bar when enabled, else None; always closes the bar."""
|
|
27
30
|
if not enabled or tqdm is None:
|
|
28
31
|
yield None
|
|
29
32
|
return
|