quality-graph-cli 0.1.1__py3-none-any.whl

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.
qg_cli/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """Quality Graph command-line application."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("quality-graph-cli")
6
+
7
+ __all__ = ["__version__"]
qg_cli/cli.py ADDED
@@ -0,0 +1,148 @@
1
+ """Command-line interface for Quality Graph."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+ from typing import TYPE_CHECKING
9
+
10
+ from qg_cli import __version__
11
+ from qg_cli.project import Project
12
+ from quality_graph_core.result import FailureKind, Metric, Provenance, Result, ResultStatus
13
+ from quality_graph_core.schema import graph_schema_json, result_schema_json
14
+
15
+ if TYPE_CHECKING:
16
+ from collections.abc import Sequence
17
+
18
+
19
+ def parser() -> argparse.ArgumentParser:
20
+ """Build the public command-line parser."""
21
+ result = argparse.ArgumentParser(prog="qg", description="Quality Graph")
22
+ result.add_argument("--version", action="version", version=__version__)
23
+ commands = result.add_subparsers(dest="command")
24
+ initialize = commands.add_parser("init", help="Create a starter Quality Graph declaration")
25
+ initialize.add_argument("--root", default=".")
26
+ initialize.add_argument("--runtime-action", required=True)
27
+ initialize.add_argument("--preset", choices=("oss", "internal"), default="oss")
28
+ initialize.add_argument("--force", action="store_true")
29
+ generate = commands.add_parser("generate", help="Generate committed GitHub workflows")
30
+ generate.add_argument("--root", default=".")
31
+ validate_project = commands.add_parser("validate", help="Validate declaration freshness")
32
+ validate_project.add_argument("--root", default=".")
33
+ graph_schema = commands.add_parser("schema", help="Render the graph JSON Schema")
34
+ graph_schema.add_argument("--output", default="-")
35
+ result_command = commands.add_parser("result", help="Work with native result JSON")
36
+ result_commands = result_command.add_subparsers(dest="result_command")
37
+ validate = result_commands.add_parser("validate", help="Validate native result JSON")
38
+ validate.add_argument("path", help="JSON file path or - for stdin")
39
+ schema = result_commands.add_parser("schema", help="Render the result JSON Schema")
40
+ schema.add_argument("--output", default="-", help="Output path or - for stdout")
41
+ emit = result_commands.add_parser("emit", help="Emit a minimal native result")
42
+ emit.add_argument("--node-id", required=True)
43
+ emit.add_argument("--title", required=True)
44
+ emit.add_argument("--status", choices=tuple(ResultStatus), required=True)
45
+ emit.add_argument("--failure-kind", choices=tuple(FailureKind))
46
+ emit.add_argument("--summary", default="")
47
+ emit.add_argument("--metric", action="append", default=[])
48
+ emit.add_argument("--repository", required=True)
49
+ emit.add_argument("--pull-request", type=int)
50
+ emit.add_argument("--head-sha", required=True)
51
+ emit.add_argument("--workflow-run-id", type=int, required=True)
52
+ emit.add_argument("--run-attempt", type=int, required=True)
53
+ emit.add_argument("--graph-digest", required=True)
54
+ emit.add_argument("--output", default="-")
55
+ return result
56
+
57
+
58
+ def main(arguments: Sequence[str] | None = None) -> int:
59
+ """Run the Quality Graph command-line interface."""
60
+ command_parser = parser()
61
+ args = command_parser.parse_args(arguments)
62
+ try:
63
+ if args.command in {"init", "generate", "validate", "schema"}:
64
+ return _project_command(args)
65
+ if args.command == "result":
66
+ return _result_command(command_parser, args)
67
+ except (OSError, TypeError, ValueError) as error:
68
+ command_parser.error(str(error))
69
+ command_parser.print_help()
70
+ return 0
71
+
72
+
73
+ def _project_command(args: argparse.Namespace) -> int:
74
+ if args.command == "init":
75
+ Project.initialize(
76
+ Path(args.root),
77
+ args.runtime_action,
78
+ preset=args.preset,
79
+ force=args.force,
80
+ )
81
+ return 0
82
+ if args.command == "generate":
83
+ Project.open(Path(args.root)).generate()
84
+ return 0
85
+ if args.command == "schema":
86
+ _write_text(args.output, graph_schema_json())
87
+ return 0
88
+ report = Project.open(Path(args.root)).validate()
89
+ if report.current:
90
+ return 0
91
+ sys.stderr.write("\n".join(report.problems) + "\n")
92
+ return 1
93
+
94
+
95
+ def _result_command(command_parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
96
+ if args.result_command == "validate":
97
+ Result.from_json(_read_text(args.path))
98
+ return 0
99
+ if args.result_command == "schema":
100
+ _write_text(args.output, result_schema_json())
101
+ return 0
102
+ if args.result_command == "emit":
103
+ _write_text(args.output, _emitted_result(args).to_json())
104
+ return 0
105
+ command_parser.print_help()
106
+ return 0
107
+
108
+
109
+ def _emitted_result(args: argparse.Namespace) -> Result:
110
+ metrics = tuple(_metric(raw) for raw in args.metric)
111
+ failure = FailureKind(args.failure_kind) if args.failure_kind is not None else None
112
+ return Result(
113
+ args.node_id,
114
+ args.title,
115
+ ResultStatus(args.status),
116
+ Provenance(
117
+ args.repository,
118
+ args.head_sha,
119
+ args.workflow_run_id,
120
+ args.run_attempt,
121
+ args.graph_digest,
122
+ args.pull_request,
123
+ ),
124
+ failure,
125
+ args.summary,
126
+ metrics,
127
+ )
128
+
129
+
130
+ def _metric(value: str) -> Metric:
131
+ label, separator, metric_value = value.partition("=")
132
+ if not separator:
133
+ message = "--metric must use label=value"
134
+ raise ValueError(message)
135
+ return Metric(label, metric_value)
136
+
137
+
138
+ def _read_text(path: str) -> str:
139
+ return sys.stdin.read() if path == "-" else Path(path).read_text()
140
+
141
+
142
+ def _write_text(path: str, value: str) -> None:
143
+ if path == "-":
144
+ sys.stdout.write(value)
145
+ else:
146
+ output = Path(path)
147
+ output.parent.mkdir(parents=True, exist_ok=True)
148
+ output.write_text(value)
qg_cli/project.py ADDED
@@ -0,0 +1,113 @@
1
+ """Manage one repository through the declarative Quality Graph seam."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from pathlib import Path
7
+ from typing import TYPE_CHECKING, Literal, Self
8
+
9
+ from qg_cli.providers import load_provider
10
+ from quality_graph_core.graph import Graph
11
+
12
+ if TYPE_CHECKING:
13
+ from quality_graph_core.provider import GeneratedProject, Provider
14
+
15
+ CONFIGURATION_PATH = Path("quality-graph.yml")
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class ValidationReport:
20
+ """Describe generated files that are missing or stale."""
21
+
22
+ problems: tuple[str, ...] = ()
23
+
24
+ @property
25
+ def current(self) -> bool:
26
+ """Return whether every generated file matches the declaration."""
27
+ return not self.problems
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class Project:
32
+ """Expose graph generation and freshness through one repository-root interface."""
33
+
34
+ root: Path
35
+ graph: Graph
36
+ provider: Provider
37
+
38
+ @classmethod
39
+ def open(cls, root: Path) -> Self:
40
+ """Load a project from its committed declaration."""
41
+ configuration = root / CONFIGURATION_PATH
42
+ if not configuration.is_file():
43
+ message = f"Quality Graph declaration does not exist: {configuration}"
44
+ raise FileNotFoundError(message)
45
+ graph = Graph.from_yaml(configuration.read_text())
46
+ return cls(root, graph, load_provider(graph.provider.name))
47
+
48
+ def render(self) -> GeneratedProject:
49
+ """Compile the project without mutating its repository."""
50
+ return self.provider.generate(self.graph)
51
+
52
+ def generate(self) -> GeneratedProject:
53
+ """Write every deterministic generated file."""
54
+ generated = self.render()
55
+ for item in generated.files:
56
+ path = self.root / item.path
57
+ path.parent.mkdir(parents=True, exist_ok=True)
58
+ path.write_text(item.content)
59
+ return generated
60
+
61
+ def validate(self) -> ValidationReport:
62
+ """Compare generated output without mutating files."""
63
+ problems: list[str] = []
64
+ for item in self.render().files:
65
+ path = self.root / item.path
66
+ if not path.is_file():
67
+ problems.append(f"missing generated file: {item.path}")
68
+ elif path.read_text() != item.content:
69
+ problems.append(f"stale generated file: {item.path}")
70
+ return ValidationReport(tuple(problems))
71
+
72
+ @classmethod
73
+ def initialize(
74
+ cls,
75
+ root: Path,
76
+ runtime_action: str,
77
+ *,
78
+ preset: Literal["oss", "internal"] = "oss",
79
+ force: bool = False,
80
+ ) -> Self:
81
+ """Create one understandable starter declaration."""
82
+ configuration = root / CONFIGURATION_PATH
83
+ if configuration.exists() and not force:
84
+ message = f"Refusing to replace existing declaration: {configuration}"
85
+ raise FileExistsError(message)
86
+ provider = load_provider("github")
87
+ root.mkdir(parents=True, exist_ok=True)
88
+ configuration.write_text(_starter_configuration(runtime_action, preset))
89
+ return cls(root, Graph.from_yaml(configuration.read_text()), provider)
90
+
91
+
92
+ def _starter_configuration(runtime_action: str, preset: Literal["oss", "internal"]) -> str:
93
+ runner = "ubuntu-latest" if preset == "oss" else "self-hosted"
94
+ return f"""version: 0
95
+ provider:
96
+ name: github
97
+ configuration:
98
+ runtime:
99
+ action: {runtime_action}
100
+
101
+ profiles:
102
+ default:
103
+ runner: {runner}
104
+ setup:
105
+ - uses: actions/checkout@v7
106
+ with:
107
+ persist-credentials: "false"
108
+
109
+ nodes:
110
+ quality:
111
+ title: Quality
112
+ run: make check
113
+ """
qg_cli/providers.py ADDED
@@ -0,0 +1,34 @@
1
+ """Discover installed hosting providers through Python package metadata."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from importlib.metadata import entry_points, version
6
+
7
+ from quality_graph_core.provider import Provider
8
+
9
+ PROVIDER_GROUP = "qg.providers"
10
+ CLI_VERSION = version("quality-graph-cli")
11
+
12
+
13
+ class ProviderNotInstalledError(ValueError):
14
+ """Report a provider requested by configuration but absent from the environment."""
15
+
16
+
17
+ def load_provider(name: str) -> Provider:
18
+ """Load one installed provider by its stable configuration name."""
19
+ matches = tuple(entry_points(group=PROVIDER_GROUP, name=name))
20
+ if not matches:
21
+ message = (
22
+ f"Provider '{name}' is not installed. "
23
+ f"Install it with: uv tool install quality-graph-cli=={CLI_VERSION} "
24
+ f"--with quality-graph-{name}=={CLI_VERSION}"
25
+ )
26
+ raise ProviderNotInstalledError(message)
27
+ if len(matches) != 1:
28
+ message = f"Provider '{name}' has multiple installed implementations"
29
+ raise RuntimeError(message)
30
+ loaded = matches[0].load()
31
+ if not isinstance(loaded, Provider):
32
+ message = f"Provider '{name}' does not satisfy the Quality Graph provider interface"
33
+ raise TypeError(message)
34
+ return loaded
qg_cli/py.typed ADDED
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,16 @@
1
+ Metadata-Version: 2.4
2
+ Name: quality-graph-cli
3
+ Version: 0.1.1
4
+ Summary: Provider-driven Quality Graph command-line application
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.12
7
+ Requires-Dist: quality-graph-core==0.1.1
8
+ Description-Content-Type: text/markdown
9
+
10
+ # qg
11
+
12
+ Provider-driven command-line application for Quality Graph projects.
13
+
14
+ The CLI discovers providers through the `qg.providers` entry-point group. Install it together
15
+ with the GitHub provider using
16
+ `uv tool install quality-graph-cli==0.1.1 --with quality-graph-github==0.1.1`.
@@ -0,0 +1,9 @@
1
+ qg_cli/__init__.py,sha256=DOcMmIldlQ1-WQkkD_jpjtPSrokdoRqa1UGtxuT3MIg,157
2
+ qg_cli/cli.py,sha256=be8O2eWad6jv2LelXpE02_VNt8L1MxMClKpaGT-eSlk,5707
3
+ qg_cli/project.py,sha256=uq8YdGKcbsh6INlQun5Va53bbenJuvJ3vWEiCnvZZwI,3609
4
+ qg_cli/providers.py,sha256=yIfBwJO8L5ijnFiI_7QcJTk30C8FklcfgnQlsbXQkkE,1257
5
+ qg_cli/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
6
+ quality_graph_cli-0.1.1.dist-info/METADATA,sha256=tsd-0HJeQqJ8xhjoXmIVeg--b0gTvz6Pi_D24VJVYW0,535
7
+ quality_graph_cli-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
8
+ quality_graph_cli-0.1.1.dist-info/entry_points.txt,sha256=i_v3UMWi6amVmWvrVGDU61IrEOTkjXXeUsOVM6CpxxM,39
9
+ quality_graph_cli-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.27.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ qg = qg_cli.cli:main