quality-graph-cli 0.1.10__tar.gz → 0.2.0__tar.gz

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.
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: quality-graph-cli
3
- Version: 0.1.10
3
+ Version: 0.2.0
4
4
  Summary: Provider-driven Quality Graph command-line application
5
5
  Project-URL: Homepage, https://quality-graph.xyz/
6
6
  Project-URL: Documentation, https://quality-graph.xyz/
7
7
  License-Expression: MIT
8
8
  Requires-Python: >=3.12
9
- Requires-Dist: quality-graph-core==0.1.10
9
+ Requires-Dist: quality-graph-core==0.2.0
10
10
  Description-Content-Type: text/markdown
11
11
 
12
12
  # qg
@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "quality-graph-cli"
7
- version = "0.1.10"
7
+ version = "0.2.0"
8
8
  description = "Provider-driven Quality Graph command-line application"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12"
11
11
  license = "MIT"
12
- dependencies = ["quality-graph-core==0.1.10"]
12
+ dependencies = ["quality-graph-core==0.2.0"]
13
13
 
14
14
  [project.urls]
15
15
  Homepage = "https://quality-graph.xyz/"
@@ -10,8 +10,15 @@ from typing import TYPE_CHECKING
10
10
 
11
11
  from qg_cli import __version__
12
12
  from qg_cli.project import Project
13
- from quality_graph_core.result import FailureKind, Metric, Provenance, Result, ResultStatus
14
- from quality_graph_core.schema import graph_schema_json, result_schema_json
13
+ from quality_graph_core.result import (
14
+ FailureKind,
15
+ GitLabProvenance,
16
+ Metric,
17
+ Provenance,
18
+ Result,
19
+ ResultStatus,
20
+ )
21
+ from quality_graph_core.schema import graph_schema_json, producer_schema_json, result_schema_json
15
22
 
16
23
  if TYPE_CHECKING:
17
24
  from collections.abc import Sequence
@@ -24,11 +31,12 @@ def parser() -> argparse.ArgumentParser:
24
31
  commands = result.add_subparsers(dest="command")
25
32
  initialize = commands.add_parser("init", help="Create a starter Quality Graph declaration")
26
33
  initialize.add_argument("--root", default=".")
27
- initialize.add_argument("--runtime-action", required=True)
34
+ initialize.add_argument("--runtime-action", default="")
35
+ initialize.add_argument("--provider", default="github")
28
36
  initialize.add_argument("--default-branch", default="main")
29
37
  initialize.add_argument("--preset", choices=("oss", "internal"), default="oss")
30
38
  initialize.add_argument("--force", action="store_true")
31
- generate = commands.add_parser("generate", help="Generate committed GitHub workflows")
39
+ generate = commands.add_parser("generate", help="Generate committed provider CI configuration")
32
40
  generate.add_argument("--root", default=".")
33
41
  validate_project = commands.add_parser("validate", help="Validate declaration freshness")
34
42
  validate_project.add_argument("--root", default=".")
@@ -53,24 +61,37 @@ def parser() -> argparse.ArgumentParser:
53
61
  validate = result_commands.add_parser("validate", help="Validate native result JSON")
54
62
  validate.add_argument("path", help="JSON file path or - for stdin")
55
63
  schema = result_commands.add_parser("schema", help="Render the result JSON Schema")
64
+ schema.add_argument("--producer", action="store_true", help="Render the producer input schema")
56
65
  schema.add_argument("--output", default="-", help="Output path or - for stdout")
66
+ schema.add_argument("--schema-version", type=int, choices=(0, 1), default=0)
57
67
  emit = result_commands.add_parser("emit", help="Emit a minimal native result")
68
+ _emission_arguments(emit)
69
+ return result
70
+
71
+
72
+ def _emission_arguments(emit: argparse.ArgumentParser) -> None:
58
73
  emit.add_argument("--node-id", required=True)
59
74
  emit.add_argument("--title", required=True)
60
75
  emit.add_argument("--status", choices=tuple(ResultStatus), required=True)
61
76
  emit.add_argument("--failure-kind", choices=tuple(FailureKind))
62
77
  emit.add_argument("--summary", default="")
63
78
  emit.add_argument("--metric", action="append", default=[])
64
- emit.add_argument("--repository", required=True)
79
+ emit.add_argument("--provider", choices=("github", "gitlab"), default="github")
80
+ emit.add_argument("--repository")
81
+ emit.add_argument("--server-url")
82
+ emit.add_argument("--project-id", type=int)
83
+ emit.add_argument("--pipeline-id", type=int)
84
+ emit.add_argument("--job-id", type=int)
85
+ emit.add_argument("--target-project-id", type=int)
86
+ emit.add_argument("--merge-request", type=int)
65
87
  emit.add_argument("--pull-request", type=int)
66
88
  emit.add_argument("--flow-id")
67
89
  emit.add_argument("--operation-id")
68
90
  emit.add_argument("--head-sha", required=True)
69
- emit.add_argument("--workflow-run-id", type=int, required=True)
70
- emit.add_argument("--run-attempt", type=int, required=True)
91
+ emit.add_argument("--workflow-run-id", type=int)
92
+ emit.add_argument("--run-attempt", type=int)
71
93
  emit.add_argument("--graph-digest", required=True)
72
94
  emit.add_argument("--output", default="-")
73
- return result
74
95
 
75
96
 
76
97
  def main(arguments: Sequence[str] | None = None) -> int:
@@ -109,13 +130,22 @@ def _github_command(command_parser: argparse.ArgumentParser, args: argparse.Name
109
130
 
110
131
  def _project_command(args: argparse.Namespace) -> int:
111
132
  if args.command == "init":
112
- Project.initialize(
113
- Path(args.root),
114
- args.runtime_action,
115
- default_branch=args.default_branch,
116
- preset=args.preset,
117
- force=args.force,
118
- )
133
+ if args.provider == "github":
134
+ Project.initialize(
135
+ Path(args.root),
136
+ args.runtime_action,
137
+ default_branch=args.default_branch,
138
+ preset=args.preset,
139
+ force=args.force,
140
+ )
141
+ else:
142
+ Project.initialize_provider(
143
+ Path(args.root),
144
+ args.provider,
145
+ default_branch=args.default_branch,
146
+ preset=args.preset,
147
+ force=args.force,
148
+ )
119
149
  return 0
120
150
  if args.command == "generate":
121
151
  Project.open(Path(args.root)).generate()
@@ -139,7 +169,10 @@ def _result_command(command_parser: argparse.ArgumentParser, args: argparse.Name
139
169
  Result.from_json(_read_text(args.path))
140
170
  return 0
141
171
  if args.result_command == "schema":
142
- _write_text(args.output, result_schema_json())
172
+ _write_text(
173
+ args.output,
174
+ producer_schema_json() if args.producer else result_schema_json(args.schema_version),
175
+ )
143
176
  return 0
144
177
  if args.result_command == "emit":
145
178
  _write_text(args.output, _emitted_result(args).to_json())
@@ -155,19 +188,45 @@ def _emitted_result(args: argparse.Namespace) -> Result:
155
188
  args.node_id,
156
189
  args.title,
157
190
  ResultStatus(args.status),
158
- Provenance(
159
- args.repository,
191
+ _emission_provenance(args),
192
+ failure,
193
+ args.summary,
194
+ metrics,
195
+ )
196
+
197
+
198
+ def _emission_provenance(args: argparse.Namespace) -> Provenance | GitLabProvenance:
199
+ required = (
200
+ ("server_url", "project_id", "pipeline_id", "job_id")
201
+ if args.provider == "gitlab"
202
+ else ("repository", "workflow_run_id", "run_attempt")
203
+ )
204
+ missing = ["--" + field.replace("_", "-") for field in required if getattr(args, field) is None]
205
+ if missing:
206
+ message = f"{args.provider} results require {', '.join(missing)}"
207
+ raise ValueError(message)
208
+ if args.provider == "gitlab":
209
+ return GitLabProvenance(
210
+ args.server_url,
211
+ args.project_id,
160
212
  args.head_sha,
161
- args.workflow_run_id,
162
- args.run_attempt,
213
+ args.pipeline_id,
214
+ args.job_id,
163
215
  args.graph_digest,
164
- args.pull_request,
216
+ args.target_project_id,
217
+ args.merge_request,
165
218
  args.flow_id,
166
219
  args.operation_id,
167
- ),
168
- failure,
169
- args.summary,
170
- metrics,
220
+ )
221
+ return Provenance(
222
+ args.repository,
223
+ args.head_sha,
224
+ args.workflow_run_id,
225
+ args.run_attempt,
226
+ args.graph_digest,
227
+ args.pull_request,
228
+ args.flow_id,
229
+ args.operation_id,
171
230
  )
172
231
 
173
232
 
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Literal, Self
9
9
 
10
10
  from qg_cli.providers import load_provider
11
11
  from quality_graph_core.graph import Graph
12
+ from quality_graph_core.provider import ProviderInitializer
12
13
 
13
14
  if TYPE_CHECKING:
14
15
  from quality_graph_core.provider import GeneratedProject, Provider
@@ -91,6 +92,19 @@ class Project:
91
92
  if path.is_symlink():
92
93
  message = f"Refusing to overwrite a generated-file symbolic link: {path}"
93
94
  raise ValueError(message)
95
+ if (
96
+ self.graph.provider.name == "gitlab"
97
+ and relative.suffix in {".yml", ".yaml"}
98
+ and path.is_file()
99
+ and not path.read_text().startswith(
100
+ "# Generated by Quality Graph. DO NOT EDIT MANUALLY."
101
+ )
102
+ ):
103
+ message = (
104
+ f"Refusing to overwrite unmanaged GitLab CI: {path}; "
105
+ "use ci-path: .qg/gitlab-ci.yml and include it"
106
+ )
107
+ raise FileExistsError(message)
94
108
 
95
109
  def _retired_paths(self, generated: GeneratedProject) -> tuple[Path, ...]:
96
110
  root = self.root.resolve()
@@ -172,15 +186,46 @@ class Project:
172
186
  preset: Literal["oss", "internal"] = "oss",
173
187
  force: bool = False,
174
188
  ) -> Self:
175
- """Create one understandable starter declaration."""
189
+ """Create a backwards-compatible GitHub starter declaration."""
190
+ provider = load_provider("github")
191
+ source = _starter_configuration(runtime_action, default_branch, preset)
192
+ return cls._initialize(root, provider, source, force=force)
193
+
194
+ @classmethod
195
+ def initialize_provider(
196
+ cls,
197
+ root: Path,
198
+ provider_name: str,
199
+ *,
200
+ default_branch: str = "main",
201
+ preset: Literal["oss", "internal"] = "oss",
202
+ force: bool = False,
203
+ ) -> Self:
204
+ """Initialize a provider that supplies its own starter declaration."""
205
+ provider = load_provider(provider_name)
206
+ if not isinstance(provider, ProviderInitializer):
207
+ message = f"Provider '{provider_name}' does not provide initialization"
208
+ raise TypeError(message)
209
+ source = provider.starter_configuration(default_branch, preset)
210
+ return cls._initialize(root, provider, source, force=force, validate_provider=False)
211
+
212
+ @classmethod
213
+ def _initialize(
214
+ cls,
215
+ root: Path,
216
+ provider: Provider,
217
+ source: str,
218
+ *,
219
+ force: bool,
220
+ validate_provider: bool = True,
221
+ ) -> Self:
176
222
  configuration = _configuration_path(root)
177
223
  if configuration.exists() and not force:
178
224
  message = f"Refusing to replace existing declaration: {configuration}"
179
225
  raise FileExistsError(message)
180
- provider = load_provider("github")
181
- source = _starter_configuration(runtime_action, default_branch, preset)
182
226
  graph = Graph.from_yaml(source)
183
- provider.generate(graph)
227
+ if validate_provider:
228
+ provider.generate(graph)
184
229
  root.mkdir(parents=True, exist_ok=True)
185
230
  configuration.write_text(source)
186
231
  return cls(root, graph, provider)