@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
@@ -3,9 +3,10 @@ import json
3
3
  import logging
4
4
  import asyncio
5
5
  import argparse
6
+ import dataclasses
6
7
  import traceback
7
8
  import sys
8
- from typing import Set
9
+ from typing import Any, Optional, Set
9
10
  import datetime
10
11
  import enum
11
12
  import pathlib
@@ -13,7 +14,6 @@ import shlex
13
14
  import webbrowser
14
15
  from termcolor import cprint
15
16
  from dataclasses import is_dataclass, asdict
16
- from collections import defaultdict
17
17
  from rich.console import Console
18
18
  from rich.table import Table
19
19
 
@@ -24,30 +24,33 @@ from gnost.reporters.analysis_html import render_analysis_html
24
24
  from gnost.analysis.core.models import (
25
25
  AnalysisConfiguration,
26
26
  SeverityLevel,
27
- UnifiedFinding,
28
- ConsolidatedReport,
29
27
  )
28
+ from gnost.cli.commands.init import InitCommand
29
+ from gnost.cli.commands.remote import RemoteTarget
30
+ from gnost.vcs.remote import RemoteError
30
31
  from gnost.cli.commands.onboard import run as onboard_run
31
- from gnost.config.settings import ConfigError, load_config, report_warnings
32
+ from gnost.config.settings import (
33
+ ANALYZE_MAX_FINDINGS,
34
+ ANALYZE_TIMEOUT,
35
+ ConfigError,
36
+ load_config,
37
+ report_warnings,
38
+ )
32
39
  from gnost.reporters.mermaid import DEFAULT_MAX_EDGES
33
40
  from gnost.cli.commands.analysis import Analysis
41
+ from gnost.ci.baseline import BaselineError
42
+ from gnost.ci.exit_codes import ExitCode
43
+ from gnost.ci.run import CiOptions, CiRun
44
+ from gnost.ci.scorecard import ScoreCard
34
45
  from gnost.analysis.utils.tool_command import RUN_TOOL_FLAG, run_tool_entry
35
46
  from gnost.utils.logger import AppLogger
47
+ from gnost.utils.layout import OutputLayout
36
48
 
37
49
  AppLogger.init(level=logging.INFO)
38
50
  logger = AppLogger.get_logger(__name__)
39
51
  analysis = Analysis()
40
52
 
41
53
 
42
- SEVERITY_WEIGHTS = {
43
- SeverityLevel.CRITICAL: 1.0,
44
- SeverityLevel.HIGH: 0.6,
45
- SeverityLevel.MEDIUM: 0.3,
46
- SeverityLevel.LOW: 0.1,
47
- SeverityLevel.INFO: 0.05,
48
- }
49
-
50
-
51
54
  def _to_dict_payload(report):
52
55
  payload = None
53
56
  if hasattr(report, "to_dict"):
@@ -98,11 +101,6 @@ def _normalize_for_json(value):
98
101
  return value
99
102
 
100
103
 
101
- def _risk_to_score(risk_score: float) -> float:
102
- clamped = max(0.0, min(100.0, risk_score))
103
- return round(10.0 * (1.0 - clamped / 100.0), 2)
104
-
105
-
106
104
  def _resolve_repo_root(path: str) -> str:
107
105
  """Nearest parent with .git or pyproject.toml; the project folder if none."""
108
106
  current = os.path.abspath(path)
@@ -122,9 +120,21 @@ def _resolve_repo_root(path: str) -> str:
122
120
  current = parent
123
121
 
124
122
 
125
- def _analysis_output_path(target_path: str) -> str:
126
- repo_root = _resolve_repo_root(target_path)
127
- return os.path.join(repo_root, "docs", "analysis", "gnost_analysis.json")
123
+ def _layout(
124
+ target_path: str,
125
+ output_dir: Optional[str] = None,
126
+ output_root: Optional[str] = None,
127
+ ) -> OutputLayout:
128
+ """Output paths; `output_root` replaces the project root (used for remote repositories)."""
129
+ return OutputLayout(output_root or _resolve_repo_root(target_path), output_dir)
130
+
131
+
132
+ def _analysis_output_path(
133
+ target_path: str,
134
+ output_dir: Optional[str] = None,
135
+ output_root: Optional[str] = None,
136
+ ) -> str:
137
+ return _layout(target_path, output_dir, output_root).analysis_json
128
138
 
129
139
 
130
140
  def _analysis_open_command(report_path: str) -> str:
@@ -148,49 +158,17 @@ def _open_analysis_report(report_path: str) -> bool:
148
158
  return False
149
159
 
150
160
 
151
- def _analysis_html_output_path(target_path: str) -> str:
152
- return _analysis_output_path(target_path).replace(".json", ".html")
153
-
161
+ def _analysis_html_output_path(
162
+ target_path: str,
163
+ output_dir: Optional[str] = None,
164
+ output_root: Optional[str] = None,
165
+ ) -> str:
166
+ return _layout(target_path, output_dir, output_root).analysis_html
154
167
 
155
- def _score_style(score: float) -> str:
156
- if score >= 8.0:
157
- return "green"
158
- if score >= 6.0:
159
- return "yellow"
160
- return "red"
161
-
162
-
163
- def _analyzer_risk(findings: list[UnifiedFinding]) -> float:
164
- if not findings:
165
- return 0.0
166
- total_weight = sum(SEVERITY_WEIGHTS.get(f.severity, 0.2) for f in findings)
167
- max_weight = max(SEVERITY_WEIGHTS.values())
168
- return round((total_weight / (len(findings) * max_weight)) * 100.0, 2)
169
-
170
-
171
- def _severity_counts(findings: list[UnifiedFinding]) -> dict[str, int]:
172
- counts = {"high": 0, "medium": 0, "low": 0, "info": 0}
173
- for finding in findings:
174
- sev = str(finding.severity).split(".")[-1].lower()
175
- if sev not in counts:
176
- sev = "info"
177
- counts[sev] += 1
178
- return counts
179
-
180
-
181
- def _print_analysis_scores(report: ConsolidatedReport) -> None:
182
- metrics = getattr(report, "analysis_metrics", [])
183
- findings_by_analyzer = defaultdict(list)
184
- for finding in getattr(report, "findings", []):
185
- findings_by_analyzer[finding.source_analyzer].append(finding)
186
-
187
- analyzer_scores = {}
188
- for metric in metrics:
189
- analyzer_scores[metric.analyzer_name] = _risk_to_score(
190
- _analyzer_risk(findings_by_analyzer.get(metric.analyzer_name, []))
191
- )
192
168
 
193
- if not analyzer_scores:
169
+ def _print_analysis_scores(card: ScoreCard) -> None:
170
+ """Print the per-analyzer score table and the final score."""
171
+ if not card.analyzers:
194
172
  return
195
173
 
196
174
  table = Table(title="Analysis Scores")
@@ -201,31 +179,119 @@ def _print_analysis_scores(report: ConsolidatedReport) -> None:
201
179
  table.add_column("Medium", justify="right", style="yellow")
202
180
  table.add_column("Low", justify="right", style="green")
203
181
 
204
- for name in sorted(analyzer_scores.keys()):
205
- score = analyzer_scores[name]
206
- findings_count = len(findings_by_analyzer.get(name, []))
207
- severity_summary = _severity_counts(findings_by_analyzer.get(name, []))
208
- score_style = _score_style(score)
182
+ for item in card.analyzers:
183
+ style = ScoreCard.style(item.score)
209
184
  table.add_row(
210
- name,
211
- f"[{score_style}]{score:.2f}[/]",
212
- f"{findings_count}",
213
- f"{severity_summary['high']}",
214
- f"{severity_summary['medium']}",
215
- f"{severity_summary['low']}",
185
+ item.name,
186
+ f"[{style}]{item.score:.2f}[/]",
187
+ f"{item.findings}",
188
+ f"{item.high}",
189
+ f"{item.medium}",
190
+ f"{item.low}",
216
191
  )
217
192
 
218
193
  console = Console()
219
194
  console.print(table)
195
+ style = ScoreCard.style(card.final_score)
196
+ console.print(f"[bold]final score:[/] [{style}]{card.final_score:.2f}[/] / 10.00")
220
197
 
221
- final_score = 0.0
222
- summary = getattr(report, "summary", {})
223
- if isinstance(summary, dict):
224
- final_score = _risk_to_score(summary.get("risk_score", 0.0))
198
+
199
+ def _update_notice() -> None:
200
+ """Say on stderr if a newer gnost exists (silent offline, in CI and in scripts)."""
201
+ from gnost.utils.update_check import UpdateNotifier
202
+
203
+ try:
204
+ allowed = load_config(os.getcwd()).check_updates
205
+ except ConfigError:
206
+ allowed = True
207
+ UpdateNotifier.standard(__version__, config_allows=allowed).notify()
208
+
209
+
210
+ class _VersionAction(argparse.Action):
211
+ """`gnost --version`: print the version, then the update notice, then exit."""
212
+
213
+ def __call__(
214
+ self,
215
+ parser: argparse.ArgumentParser,
216
+ namespace: argparse.Namespace,
217
+ values: Any,
218
+ option_string: Optional[str] = None,
219
+ ) -> None:
220
+ """Print the version and the notice, then exit."""
221
+ print(f"gnost {__version__}")
222
+ _update_notice()
223
+ parser.exit()
224
+
225
+
226
+ def _open(args: argparse.Namespace) -> int:
227
+ """gnost open: the flow explorer, the analysis report or a file."""
228
+ from gnost.cli.commands.onboard import resolve_repo_root
229
+ from gnost.cli.commands.show import run as show_run
230
+
231
+ try:
232
+ config = load_config(os.getcwd())
233
+ except ConfigError:
234
+ config = None
235
+ layout = OutputLayout(
236
+ resolve_repo_root(os.getcwd()), config.output_dir if config else None
237
+ )
238
+ target = str(args.target).lower()
239
+
240
+ if target == "flow":
241
+ flow_file = args.path
242
+ explicit_view = args.view != "auto"
243
+ if not flow_file:
244
+ candidates = [
245
+ layout.flow_html if not explicit_view else None,
246
+ os.path.join(layout.flow_dir, "flow-complete.mmd"),
247
+ ]
248
+ flow_file = next((c for c in candidates if c and os.path.isfile(c)), None)
249
+ if not flow_file:
250
+ legacy = os.path.join(layout.legacy_flow_dir, "flow-complete.mmd")
251
+ if os.path.isfile(legacy):
252
+ print(f"gnost: {layout.moved_notice()}", file=sys.stderr)
253
+ flow_file = legacy
254
+ if not flow_file or not os.path.isfile(flow_file):
255
+ logger.error(f"Flow diagram not found in {layout.folder}")
256
+ logger.error("Run `gnost onboard .` first")
257
+ return 1
258
+ return show_run(flow_file, args.output, not args.no_open, args.view)
259
+
260
+ if target not in {"report", "rpt"}:
261
+ if not os.path.isfile(args.target):
262
+ logger.error(
263
+ f"Unsupported target: {args.target}. Use report, flow, "
264
+ "or the path of a .mmd, .md or .html file"
265
+ )
266
+ return 2
267
+ return show_run(args.target, args.output, not args.no_open, args.view)
268
+
269
+ if getattr(args, "path", None):
270
+ report_path = os.path.abspath(args.path)
225
271
  else:
226
- final_score = 0.0
227
- final_style = _score_style(final_score)
228
- console.print(f"[bold]final score:[/] [{final_style}]{final_score:.2f}[/] / 10.00")
272
+ report_path = layout.analysis_html
273
+ if not os.path.isfile(report_path) and os.path.isfile(
274
+ layout.legacy_analysis_html
275
+ ):
276
+ print(f"gnost: {layout.moved_notice()}", file=sys.stderr)
277
+ report_path = layout.legacy_analysis_html
278
+ if not os.path.isfile(report_path):
279
+ logger.error(f"Report not found: {report_path}")
280
+ logger.error(
281
+ "Run `gnost analyze -o` first to generate "
282
+ f"{layout.relative_name}/analysis/analysis.html"
283
+ )
284
+ return 1
285
+
286
+ if not _open_analysis_report(report_path):
287
+ fallback = _analysis_open_command(report_path)
288
+ logger.error(
289
+ f"Unable to open report automatically using webbrowser. Use: {fallback}"
290
+ )
291
+ return 1
292
+
293
+ cprint(f"Opened report: {report_path}", "green")
294
+ return 0
229
295
 
230
296
 
231
297
  def main():
@@ -251,7 +317,8 @@ def main():
251
317
  " --inject Inject onboarding link into README.md\n"
252
318
  " --layered Produce Layered mermaid as Entry -> Core -> Leaf\n"
253
319
  " --depth DEPTH Limit execution flow depth (e.g. --depth 2)\n"
254
- " --json [FILE] Also write insights as JSON (default: docs/insights/gnost_insights.json)\n"
320
+ " --json FILE Write the insights JSON to FILE instead of .gnost/insights.json\n"
321
+ " --no-html Do not write the flow explorer page (.gnost/flow.html)\n"
255
322
  " --insights-only Write only the insights JSON\n"
256
323
  " --max-edges N Largest diagram drawn file by file (default 80); bigger ones group by folder\n"
257
324
  " --collapse [LEVEL] Group diagrams by folder, LEVEL folders deep (default 1)\n\n"
@@ -259,7 +326,7 @@ def main():
259
326
  " path File or directory to analyze (default: .)\n"
260
327
  " -a, --analyzer Enable only specific analyzers\n"
261
328
  " --parallel Run analyzers in parallel\n"
262
- " -o, --out Write report to docs/analysis/gnost_analysis.json and gnost_analysis.html\n"
329
+ " -o, --out Write the report to .gnost/analysis/analysis.json and analysis.html\n"
263
330
  " -v, --verbose Show traceback on failures\n"
264
331
  " --quiet Reduce logs; keep warnings/errors only\n"
265
332
  " --list-analyzers List available analyzers and exit\n"
@@ -268,14 +335,37 @@ def main():
268
335
  " --no-progress Hide progress updates\n"
269
336
  " --max-findings N Per-analyzer findings limit (default: 1000)\n\n"
270
337
  " files:\n"
271
- " --top Number of files to show (default: 5)\n"
272
- " open:\n"
273
- " report|rpt Open the generated report in browser\n"
274
- " Shortcut alias: gnost open rpt\n"
338
+ " --top Number of files to show (default: 5)\n\n"
339
+ " init:\n"
340
+ " path Project folder (default: .)\n"
341
+ " --print Print the default settings instead of writing .gnost.toml\n"
342
+ " --force Overwrite files that already exist\n"
343
+ " --dry-run Show what would change, write nothing\n"
344
+ + "".join(
345
+ f" {'--' + i.flag:<16} {i.help}\n" for i in InitCommand.available()
346
+ )
347
+ + "\n"
348
+ " onboard|analyze|changes also take an https:// or ssh repository address\n"
349
+ " in place of the folder (cloned to a temporary folder, results go to the\n"
350
+ " current folder), and --ref BRANCH to pick a branch or tag.\n\n"
351
+ " changes:\n"
352
+ " refs BASE or BASE..HEAD, compared like a pull request\n"
353
+ " --depth N How far to follow importers (default 3)\n"
354
+ " --format text|markdown|json What to print (files go to .gnost/changes/)\n"
355
+ " --findings Also run the analyzers on the changed Python files\n"
356
+ " --no-cycles Skip scanning the base commit\n\n"
357
+ " open|show:\n"
358
+ " target report|rpt (default): the analysis report;\n"
359
+ " flow: the flow explorer; or a .mmd, .md or .html file\n"
360
+ " (`show` takes only a file)\n"
361
+ " --path FILE Custom report or diagram path\n"
362
+ " --view auto|graph|mermaid Interactive graph for big diagrams (auto), or force one\n"
363
+ " -o, --output FILE Where to save the HTML page (default: a temp file)\n"
364
+ " --no-open Write the HTML but do not open a browser\n\n"
275
365
  "Use `gnost <command> --help` for full command options."
276
366
  ),
277
367
  )
278
- parser.add_argument("--version", action="version", version=f"gnost {__version__}")
368
+ parser.add_argument("--version", action=_VersionAction, nargs=0)
279
369
 
280
370
  sub = parser.add_subparsers(
281
371
  dest="cmd",
@@ -349,13 +439,18 @@ def main():
349
439
  const="",
350
440
  default=None,
351
441
  metavar="FILE",
352
- help="Also write the insights as JSON "
353
- "(default: docs/insights/gnost_insights.json)",
442
+ help="Write the insights JSON to FILE instead of the default "
443
+ "(.gnost/insights.json, which is always written)",
444
+ )
445
+ onboard.add_argument(
446
+ "--no-html",
447
+ action="store_true",
448
+ help="Do not write the flow explorer page (.gnost/flow.html)",
354
449
  )
355
450
  onboard.add_argument(
356
451
  "--insights-only",
357
452
  action="store_true",
358
- help="Write only the insights JSON; skip ONBOARD.md and the diagrams",
453
+ help="Write only the insights JSON; skip ONBOARD.md, the diagrams and the page",
359
454
  )
360
455
  onboard.add_argument(
361
456
  "--max-edges",
@@ -429,6 +524,43 @@ def main():
429
524
  action="store_true",
430
525
  help="Hide progress updates while analysis is running.",
431
526
  )
527
+ analyze.add_argument(
528
+ "--fail-under",
529
+ type=float,
530
+ default=None,
531
+ metavar="SCORE",
532
+ help="Exit with code 3 when the final score (0 to 10) is below SCORE",
533
+ )
534
+ analyze.add_argument(
535
+ "--baseline",
536
+ nargs="?",
537
+ const="",
538
+ default=None,
539
+ metavar="FILE",
540
+ help="Report only findings that are not in this baseline "
541
+ "(default file: .gnost/baseline.json)",
542
+ )
543
+ analyze.add_argument(
544
+ "--write-baseline",
545
+ nargs="?",
546
+ const="",
547
+ default=None,
548
+ metavar="FILE",
549
+ help="Save today's findings as the baseline (default file: .gnost/baseline.json)",
550
+ )
551
+ analyze.add_argument(
552
+ "--fail-on-new",
553
+ action="store_true",
554
+ help="Exit with code 3 when there are findings that are not in the baseline",
555
+ )
556
+ analyze.add_argument(
557
+ "--sarif",
558
+ nargs="?",
559
+ const="",
560
+ default=None,
561
+ metavar="FILE",
562
+ help="Write the findings as SARIF 2.1.0 (default file: .gnost/analysis/analysis.sarif)",
563
+ )
432
564
  analyze.add_argument(
433
565
  "--max-findings",
434
566
  type=int,
@@ -445,7 +577,7 @@ def main():
445
577
  default="report",
446
578
  help=(
447
579
  "report (default, alias: rpt): the analysis report; "
448
- "flow: the flow explorer (docs/flow/flow-complete.mmd); "
580
+ "flow: the flow explorer (.gnost/flow.html); "
449
581
  "or a .mmd, .md or .html file"
450
582
  ),
451
583
  )
@@ -464,6 +596,71 @@ def main():
464
596
  "--no-open", action="store_true", help="Write the HTML page but do not open it"
465
597
  )
466
598
 
599
+ changes_cmd = sub.add_parser(
600
+ "changes",
601
+ help="What a change touches: files, blast radius, risk, routes, cycles",
602
+ )
603
+ changes_cmd.add_argument(
604
+ "refs", help="BASE or BASE..HEAD (for example origin/main or v0.5.3..HEAD)"
605
+ )
606
+ changes_cmd.add_argument(
607
+ "path", nargs="?", default=".", help="Project folder or repository address"
608
+ )
609
+ changes_cmd.add_argument(
610
+ "--depth", type=int, default=3, help="How far to follow importers (default 3)"
611
+ )
612
+ changes_cmd.add_argument(
613
+ "--format",
614
+ choices=["text", "markdown", "json"],
615
+ default="text",
616
+ help="What to print (the files in .gnost/changes/ are always written)",
617
+ )
618
+ changes_cmd.add_argument(
619
+ "--findings",
620
+ action="store_true",
621
+ help="Also run the analyzers on the changed Python files (slower)",
622
+ )
623
+ changes_cmd.add_argument(
624
+ "--no-cycles",
625
+ action="store_true",
626
+ help="Skip scanning the base commit (no new-cycle or removed-route comparison)",
627
+ )
628
+ changes_cmd.add_argument(
629
+ "--no-write", action="store_true", help="Do not write .gnost/changes/"
630
+ )
631
+
632
+ for command in (onboard, analyze, changes_cmd):
633
+ command.add_argument(
634
+ "--ref",
635
+ help="For a repository address: the branch or tag to clone (default: its default branch)",
636
+ )
637
+
638
+ init_cmd = sub.add_parser(
639
+ "init",
640
+ help="Write a complete .gnost.toml, and optionally add GNOST to your build",
641
+ )
642
+ init_cmd.add_argument("path", nargs="?", default=".", help="Project folder")
643
+ init_cmd.add_argument(
644
+ "--force", action="store_true", help="Overwrite files that already exist"
645
+ )
646
+ init_cmd.add_argument(
647
+ "--print",
648
+ dest="print_only",
649
+ action="store_true",
650
+ help="Print the default settings instead of writing the file",
651
+ )
652
+ init_cmd.add_argument(
653
+ "--dry-run", action="store_true", help="Show what would change, write nothing"
654
+ )
655
+ for integration in InitCommand.available():
656
+ init_cmd.add_argument(
657
+ f"--{integration.flag}",
658
+ action="append_const",
659
+ const=integration.flag,
660
+ dest="integrations",
661
+ help=integration.help,
662
+ )
663
+
467
664
  show_cmd = sub.add_parser(
468
665
  "show", help="Same as `gnost open FILE` (kept as a shorter name)"
469
666
  )
@@ -480,6 +677,57 @@ def main():
480
677
  )
481
678
 
482
679
  args = parser.parse_args()
680
+ return _run_remote_or_local(args)
681
+
682
+
683
+ def _run_remote_or_local(args: argparse.Namespace) -> int:
684
+ """Run the command; if the path is a repository address, clone it first (and clean up)."""
685
+ try:
686
+ target = RemoteTarget.from_args(args)
687
+ if target is None:
688
+ return _dispatch(args)
689
+ with target.open() as folder:
690
+ args.path = folder
691
+ args.output_root = (
692
+ os.getcwd()
693
+ ) # results go to the current folder, not the clone
694
+ args.remote = True
695
+ args.source = target.url.text
696
+ return _dispatch(args)
697
+ except RemoteError as exc:
698
+ print(f"gnost: {exc}", file=sys.stderr)
699
+ return ExitCode.USAGE
700
+
701
+
702
+ def _dispatch(args: argparse.Namespace) -> int:
703
+ """Run one parsed command."""
704
+ output_root = getattr(args, "output_root", None)
705
+ remote = getattr(args, "remote", False)
706
+ if args.cmd == "init":
707
+ from gnost.cli.commands.init import run as init_run
708
+
709
+ return init_run(
710
+ args.path,
711
+ selected=args.integrations or [],
712
+ force=args.force,
713
+ print_only=args.print_only,
714
+ dry_run=args.dry_run,
715
+ )
716
+
717
+ if args.cmd == "changes":
718
+ from gnost.cli.commands.changes import run as changes_run
719
+
720
+ return changes_run(
721
+ args.path,
722
+ args.refs,
723
+ depth=args.depth,
724
+ output_format=args.format,
725
+ findings=args.findings,
726
+ compare_base=not args.no_cycles,
727
+ write=not args.no_write,
728
+ output_root=output_root,
729
+ remote=remote,
730
+ )
483
731
 
484
732
  if args.cmd == "show":
485
733
  from gnost.cli.commands.show import run as show_run
@@ -488,11 +736,13 @@ def main():
488
736
 
489
737
  if args.cmd == "version":
490
738
  print(f"gnost {__version__}")
739
+ _update_notice()
491
740
  return 0
492
741
 
493
742
  if args.cmd in ("onboard", "analyze"):
494
743
  try:
495
- config = load_config(args.path)
744
+ # A remote repository's own .gnost.toml is never read (output_dir could point anywhere).
745
+ config = load_config(output_root if remote else args.path)
496
746
  except ConfigError as exc:
497
747
  print(f"gnost: {exc}", file=sys.stderr)
498
748
  return 2
@@ -519,6 +769,17 @@ def main():
519
769
  ),
520
770
  exclude=config.exclude,
521
771
  caution=config.caution_settings(),
772
+ output_dir=config.output_dir,
773
+ html=not getattr(args, "no_html", False),
774
+ history=(
775
+ dataclasses.replace(config.history_settings(), allow_shallow=True)
776
+ if remote
777
+ else config.history_settings()
778
+ ),
779
+ risk=config.risk_settings(),
780
+ output_root=output_root,
781
+ source=args.source if remote else None,
782
+ footer=config.footer,
522
783
  )
523
784
  return 0
524
785
 
@@ -533,7 +794,14 @@ def main():
533
794
  target_path = os.path.abspath(args.path)
534
795
  if not os.path.exists(target_path):
535
796
  logger.error(f"Error: path not found: {target_path}")
536
- return 2
797
+ return ExitCode.USAGE
798
+
799
+ ci_options = CiOptions.from_args(
800
+ args, config, _layout(target_path, config.output_dir, output_root)
801
+ )
802
+ if ci_options.problem():
803
+ logger.error(f"Error: {ci_options.problem()}")
804
+ return ExitCode.USAGE
537
805
 
538
806
  if not args.verbose:
539
807
  logging.getLogger("asyncio").setLevel(logging.CRITICAL)
@@ -551,7 +819,7 @@ def main():
551
819
 
552
820
  if not reader_files:
553
821
  logger.warning("⚠️ No Python files found after filtering.")
554
- return 0
822
+ return ExitCode.OK
555
823
 
556
824
  enabled_analyzers: Set[str] = set(
557
825
  args.analyzer or config.get("analyze", "analyzers", [])
@@ -564,9 +832,13 @@ def main():
564
832
  args.parallel or config.get("analyze", "parallel", False)
565
833
  ),
566
834
  include_low_confidence=False,
567
- timeout_seconds=int(config.pick("analyze", "timeout", args.timeout, 900)),
835
+ timeout_seconds=int(
836
+ config.pick("analyze", "timeout", args.timeout, ANALYZE_TIMEOUT)
837
+ ),
568
838
  max_findings_per_analyzer=int(
569
- config.pick("analyze", "max_findings", args.max_findings, 1000)
839
+ config.pick(
840
+ "analyze", "max_findings", args.max_findings, ANALYZE_MAX_FINDINGS
841
+ )
570
842
  ),
571
843
  files=reader_files,
572
844
  )
@@ -580,23 +852,40 @@ def main():
580
852
  )
581
853
  except (KeyboardInterrupt, asyncio.CancelledError):
582
854
  logger.info("Interrupted.")
583
- return 130
855
+ return ExitCode.INTERRUPTED
584
856
  except Exception as e:
585
857
  logger.error(f"Error during analysis: {e}")
586
858
  if args.verbose:
587
859
  traceback.print_exc()
588
- return 1
860
+ return ExitCode.ERROR
589
861
 
590
- payload = _to_dict_payload(report)
591
- html_output = _analysis_html_output_path(target_path)
862
+ try:
863
+ outcome = CiRun(
864
+ ci_options, _resolve_repo_root(target_path), reader_files
865
+ ).process(report)
866
+ except BaselineError as exc:
867
+ logger.error(f"Error: {exc}")
868
+ return ExitCode.USAGE
869
+
870
+ payload = _to_dict_payload(outcome.report)
871
+ if outcome.baseline_summary():
872
+ payload["baseline"] = outcome.baseline_summary()
873
+ html_output = _analysis_html_output_path(
874
+ target_path, config.output_dir, output_root
875
+ )
592
876
  if args.out:
593
877
  try:
594
- output_file = _analysis_output_path(target_path)
878
+ _layout(target_path, config.output_dir, output_root).prepare()
879
+ output_file = _analysis_output_path(
880
+ target_path, config.output_dir, output_root
881
+ )
595
882
  analysis.write_json_file(output_file, payload, compact=args.compact)
596
883
  logger.info(f"✅ Findings saved to {output_file}")
597
884
  if args.quiet:
598
885
  cprint(f"✅ Findings saved to {output_file}", "green")
599
- html_output = _analysis_html_output_path(target_path)
886
+ html_output = _analysis_html_output_path(
887
+ target_path, config.output_dir, output_root
888
+ )
600
889
  render_analysis_html(payload, html_output)
601
890
  logger.info(f"✅ Interactive HTML report saved to {html_output}")
602
891
  if args.quiet:
@@ -605,13 +894,18 @@ def main():
605
894
  )
606
895
  except Exception as e:
607
896
  logger.error(
608
- f"❌ Failed to write output file '{_analysis_output_path(target_path)}': {e}, use verbose to check"
897
+ f"❌ Failed to write output file '{_analysis_output_path(target_path, config.output_dir, output_root)}': {e}, use verbose to check"
609
898
  )
610
899
  if args.verbose:
611
900
  traceback.print_exc()
612
- return 1
901
+ return ExitCode.ERROR
613
902
 
614
- _print_analysis_scores(report)
903
+ _print_analysis_scores(outcome.card)
904
+ for note in outcome.notes:
905
+ if args.quiet:
906
+ cprint(note, "green")
907
+ else:
908
+ logger.info(note)
615
909
  if args.out:
616
910
  open_cmd = _analysis_open_command(html_output)
617
911
  console = Console()
@@ -626,57 +920,14 @@ def main():
626
920
  cprint(msg, "yellow")
627
921
  else:
628
922
  logger.info(msg)
629
- return 0
923
+ if not outcome.gate.passed:
924
+ for message in outcome.gate.messages:
925
+ logger.error(f"Quality gate failed: {message}")
926
+ return ExitCode.GATE_FAILED
927
+ return ExitCode.OK
630
928
 
631
929
  if args.cmd == "open":
632
- normalized_target = str(args.target).lower()
633
- if normalized_target == "flow" or (
634
- normalized_target not in {"report", "rpt"}
635
- and not os.path.isfile(args.target)
636
- ):
637
- if normalized_target != "flow":
638
- logger.error(
639
- f"Unsupported target: {args.target}. Use report, flow, "
640
- "or the path of a .mmd, .md or .html file"
641
- )
642
- return 2
643
- from gnost.cli.commands.show import run as show_run
644
-
645
- flow_file = args.path or os.path.join(
646
- os.getcwd(), "docs", "flow", "flow-complete.mmd"
647
- )
648
- if not os.path.isfile(flow_file):
649
- logger.error(f"Flow diagram not found: {flow_file}")
650
- logger.error("Run `gnost onboard .` first")
651
- return 1
652
- return show_run(flow_file, args.output, not args.no_open, args.view)
653
- if normalized_target not in {"report", "rpt"}:
654
- from gnost.cli.commands.show import run as show_run
655
-
656
- return show_run(args.target, args.output, not args.no_open, args.view)
657
-
658
- report_path = (
659
- os.path.abspath(args.path)
660
- if getattr(args, "path", None)
661
- else _analysis_html_output_path(os.getcwd())
662
- )
663
- if not os.path.isfile(report_path):
664
- logger.error(f"Report not found: {report_path}")
665
- logger.error(
666
- "Run `gnost analyze -o` first to generate "
667
- "docs/analysis/gnost_analysis.html"
668
- )
669
- return 1
670
-
671
- if not _open_analysis_report(report_path):
672
- fallback = _analysis_open_command(report_path)
673
- logger.error(
674
- f"Unable to open report automatically using webbrowser. Use: {fallback}"
675
- )
676
- return 1
677
-
678
- cprint(f"Opened report: {report_path}", "green")
679
- return 0
930
+ return _open(args)
680
931
 
681
932
  include = args.include.split(",") if args.include else []
682
933
  exclude = args.exclude.split(",") if args.exclude else []