quality-graph-cli 0.1.1__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.
- quality_graph_cli-0.1.1/.gitignore +20 -0
- quality_graph_cli-0.1.1/PKG-INFO +16 -0
- quality_graph_cli-0.1.1/README.md +7 -0
- quality_graph_cli-0.1.1/pyproject.toml +21 -0
- quality_graph_cli-0.1.1/src/qg_cli/__init__.py +7 -0
- quality_graph_cli-0.1.1/src/qg_cli/cli.py +148 -0
- quality_graph_cli-0.1.1/src/qg_cli/project.py +113 -0
- quality_graph_cli-0.1.1/src/qg_cli/providers.py +34 -0
- quality_graph_cli-0.1.1/src/qg_cli/py.typed +1 -0
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
.pytest_cache/
|
|
5
|
+
.mypy_cache/
|
|
6
|
+
.ruff_cache/
|
|
7
|
+
.coverage
|
|
8
|
+
coverage.json
|
|
9
|
+
coverage.xml
|
|
10
|
+
htmlcov/
|
|
11
|
+
coverage-report/
|
|
12
|
+
dist/
|
|
13
|
+
build/
|
|
14
|
+
*.egg-info/
|
|
15
|
+
.mutmut-cache/
|
|
16
|
+
mutants/
|
|
17
|
+
reports/
|
|
18
|
+
.tools/
|
|
19
|
+
node_modules/
|
|
20
|
+
.DS_Store
|
|
@@ -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,7 @@
|
|
|
1
|
+
# qg
|
|
2
|
+
|
|
3
|
+
Provider-driven command-line application for Quality Graph projects.
|
|
4
|
+
|
|
5
|
+
The CLI discovers providers through the `qg.providers` entry-point group. Install it together
|
|
6
|
+
with the GitHub provider using
|
|
7
|
+
`uv tool install quality-graph-cli==0.1.1 --with quality-graph-github==0.1.1`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling==1.27.0"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "quality-graph-cli"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
description = "Provider-driven Quality Graph command-line application"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
dependencies = ["quality-graph-core==0.1.1"]
|
|
13
|
+
|
|
14
|
+
[project.scripts]
|
|
15
|
+
qg = "qg_cli.cli:main"
|
|
16
|
+
|
|
17
|
+
[tool.uv.sources]
|
|
18
|
+
quality-graph-core = { workspace = true }
|
|
19
|
+
|
|
20
|
+
[tool.hatch.build.targets.wheel]
|
|
21
|
+
packages = ["src/qg_cli"]
|
|
@@ -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)
|
|
@@ -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
|
+
"""
|
|
@@ -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
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|