@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,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 Python's resource tracker, which relaunches sys.executable.
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(enabled=False, total=None, desc=None):
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