quality-graph-cli 0.1.9__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.9
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.9
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.9"
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.9"]
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
@@ -57,6 +58,7 @@ class Project:
57
58
  def generate(self) -> GeneratedProject:
58
59
  """Write every deterministic generated file."""
59
60
  generated = self.render()
61
+ self._validate_output_paths(generated)
60
62
  prettier_ignore = self._prettier_ignore(generated)
61
63
  retired = self._retired_paths(generated)
62
64
  for path in retired:
@@ -80,14 +82,46 @@ class Project:
80
82
  ignore_path.write_text(prettier_ignore)
81
83
  return generated
82
84
 
85
+ def _validate_output_paths(self, generated: GeneratedProject) -> None:
86
+ root = self.root.resolve()
87
+ for relative in (*[item.path for item in generated.files], PRETTIER_IGNORE_PATH):
88
+ path = self.root / relative
89
+ if root not in path.resolve().parents:
90
+ message = f"Generated file is outside the project root: {path}"
91
+ raise ValueError(message)
92
+ if path.is_symlink():
93
+ message = f"Refusing to overwrite a generated-file symbolic link: {path}"
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)
108
+
83
109
  def _retired_paths(self, generated: GeneratedProject) -> tuple[Path, ...]:
84
110
  root = self.root.resolve()
85
- paths = tuple(self.root / path for path in generated.retired_files)
86
- for path in paths:
111
+ required = tuple(self.root / path for path in generated.retired_files)
112
+ optional = tuple(self.root / path for path in generated.retired_if_generated)
113
+ for path in (*required, *optional):
87
114
  if root not in path.resolve().parents:
88
115
  message = f"Retired workflow is outside the project root: {path}"
89
116
  raise ValueError(message)
90
- return paths
117
+ owned = tuple(
118
+ path
119
+ for path in optional
120
+ if not path.is_symlink()
121
+ and path.is_file()
122
+ and path.read_text().startswith("# Generated by Quality Graph. DO NOT EDIT MANUALLY.")
123
+ )
124
+ return (*required, *owned)
91
125
 
92
126
  def generated_files(self) -> tuple[PurePosixPath, ...]:
93
127
  """Return stable repository-relative compiler-owned paths."""
@@ -97,6 +131,7 @@ class Project:
97
131
  """Compare generated output without mutating files."""
98
132
  problems: list[str] = []
99
133
  generated = self.render()
134
+ self._validate_output_paths(generated)
100
135
  problems.extend(
101
136
  f"retired generated file: {path.relative_to(self.root)}"
102
137
  for path in self._retired_paths(generated)
@@ -151,15 +186,46 @@ class Project:
151
186
  preset: Literal["oss", "internal"] = "oss",
152
187
  force: bool = False,
153
188
  ) -> Self:
154
- """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:
155
222
  configuration = _configuration_path(root)
156
223
  if configuration.exists() and not force:
157
224
  message = f"Refusing to replace existing declaration: {configuration}"
158
225
  raise FileExistsError(message)
159
- provider = load_provider("github")
160
- source = _starter_configuration(runtime_action, default_branch, preset)
161
226
  graph = Graph.from_yaml(source)
162
- provider.generate(graph)
227
+ if validate_provider:
228
+ provider.generate(graph)
163
229
  root.mkdir(parents=True, exist_ok=True)
164
230
  configuration.write_text(source)
165
231
  return cls(root, graph, provider)