revtrend 0.1.0__tar.gz

revtrend-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Holesch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

revtrend-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: revtrend
+Version: 0.1.0
+Summary: Track numeric metrics per git commit and visualize trends in Grafana
+Author: Simon Holesch
+Author-email: Simon Holesch <simon@holesch.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: prometheus-client>=0.26.0
+Requires-Dist: pydantic>=2.14.3
+Requires-Dist: pyjwt[crypto]
+Requires-Dist: uvicorn
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/holesch/revtrend
+Project-URL: Source, https://github.com/holesch/revtrend
+Project-URL: Issues, https://github.com/holesch/revtrend/issues
+Description-Content-Type: text/markdown
+
+# revtrend
+
+Track numeric metrics per git commit (image size, binary size, test duration,
+coverage, …) and visualize them over time in Grafana.
+
+Data is keyed by commit SHA. Which commits belong to a view is answered from
+a bare mirror of the project's repository: the first-parent history of the
+selected ref, compared against a base ref.
+
+## Service
+
+`revtrend-server --config /etc/revtrend/config.toml`, see
+[contrib/config.example.toml](https://github.com/holesch/revtrend/blob/master/contrib/config.example.toml) and
+[contrib/revtrend.service](https://github.com/holesch/revtrend/blob/master/contrib/revtrend.service).
+
+All `/api/v1` endpoints require a bearer JWT from one of the configured
+issuers. Roles per project: `reader` < `writer` < `admin`.
+
+| Endpoint | Role | |
+|---|---|---|
+| `POST /api/v1/projects/{project}/measurements` | writer | ingest one run for a commit |
+| `GET /api/v1/projects/{project}/series` | reader | flat rows for Grafana (`metric`, `ref`, `base`, `from`, `to`, `labels`, `agg`) |
+| `GET /api/v1/projects/{project}/compare` | reader | head vs. nearest measured commit from the merge base with `base` |
+| `GET /api/v1/projects` | any | projects the caller can read |
+| `GET /api/v1/projects/{project}/refs` | reader | branches (`active_since`, `match`) |
+| `GET /api/v1/projects/{project}/metrics` | reader | metric names and label values |
+| `DELETE /api/v1/projects/{project}/measurements` | admin | delete by `run_id` or `metric` |
+| `GET /auth/cli/{config,callback,poll}` | none | PKCE code relay for the CLI |
+| `GET /healthz`, `GET /metrics` | none | health and Prometheus metrics |
+
+`/metrics` is unauthenticated; don't expose it through the reverse proxy.
+
+Ingest example:
+
+```sh
+curl -fsS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    --data '{"sha": "<40 hex>", "run_id": "'"$BUILD_URL"'", "metrics": [
+              {"name": "image.size_bytes", "value": 81234432,
+               "labels": {"machine": "amd64", "image": "core-image"}}]}' \
+    https://revtrend.example/api/v1/projects/myproject/measurements
+```
+
+The measurement `source` (`ci` or `manual`) is derived from the token issuer,
+never from the request. Per commit, CI runs take precedence over manual runs.
+
+Each measurement records the submitter as `<issuer name>:<sub>`, the stable
+OIDC identifier. For a readable audit trail, set `display_claims` on an issuer
+(e.g. `["preferred_username", "name"]`): the first claim present in the token
+is stored as `submitted_name`.
+
+## CLI
+
+```sh
+pipx install revtrend
+export REVTREND_URL=https://revtrend.example
+
+revtrend login
+revtrend push --project myproject --sha HEAD metrics.json
+revtrend compare --project myproject --head HEAD --base release/1.0
+```
+
+`login` prints a URL to open in any browser, also from an ssh session: the
+service receives the login redirect and relays the authorization code to the
+CLI, which redeems it with its PKCE verifier. Tokens are cached in
+`~/.cache/revtrend/sessions.json` and refreshed automatically.
+`$REVTREND_TOKEN` overrides the cached session.
+
+`push` takes a JSON array of metrics (`-` reads stdin):
+
+```json
+[{"name": "image.size_bytes", "value": 81234432,
+  "labels": {"machine": "amd64", "image": "core-image"}}]
+```
+
+`--sha` and `--head` are resolved in the current repository, so backfilling
+means checking out an old commit, measuring and pushing. The commit must exist
+in the remote. The run id defaults to `manual-<user>-<timestamp>`; pass
+`--run-id` to make a retry idempotent.
+
+`compare` prints head vs. baseline per series, or the raw response with
+`--json`.
+
+## Development
+
+```sh
+uv sync
+```
+
+Tests:
+
+```sh
+uv run pytest
+```
+
+Static checks:
+
+```sh
+uv run ruff check
+uv run ruff format --check
+```
+
+Entry points:
+
+- `revtrend-server` — HTTP API (FastAPI + uvicorn)
+- `revtrend` — CLI for pushing measurements and comparing commits

revtrend-0.1.0/README.md

@@ -0,0 +1,105 @@
+# revtrend
+
+Track numeric metrics per git commit (image size, binary size, test duration,
+coverage, …) and visualize them over time in Grafana.
+
+Data is keyed by commit SHA. Which commits belong to a view is answered from
+a bare mirror of the project's repository: the first-parent history of the
+selected ref, compared against a base ref.
+
+## Service
+
+`revtrend-server --config /etc/revtrend/config.toml`, see
+[contrib/config.example.toml](https://github.com/holesch/revtrend/blob/master/contrib/config.example.toml) and
+[contrib/revtrend.service](https://github.com/holesch/revtrend/blob/master/contrib/revtrend.service).
+
+All `/api/v1` endpoints require a bearer JWT from one of the configured
+issuers. Roles per project: `reader` < `writer` < `admin`.
+
+| Endpoint | Role | |
+|---|---|---|
+| `POST /api/v1/projects/{project}/measurements` | writer | ingest one run for a commit |
+| `GET /api/v1/projects/{project}/series` | reader | flat rows for Grafana (`metric`, `ref`, `base`, `from`, `to`, `labels`, `agg`) |
+| `GET /api/v1/projects/{project}/compare` | reader | head vs. nearest measured commit from the merge base with `base` |
+| `GET /api/v1/projects` | any | projects the caller can read |
+| `GET /api/v1/projects/{project}/refs` | reader | branches (`active_since`, `match`) |
+| `GET /api/v1/projects/{project}/metrics` | reader | metric names and label values |
+| `DELETE /api/v1/projects/{project}/measurements` | admin | delete by `run_id` or `metric` |
+| `GET /auth/cli/{config,callback,poll}` | none | PKCE code relay for the CLI |
+| `GET /healthz`, `GET /metrics` | none | health and Prometheus metrics |
+
+`/metrics` is unauthenticated; don't expose it through the reverse proxy.
+
+Ingest example:
+
+```sh
+curl -fsS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    --data '{"sha": "<40 hex>", "run_id": "'"$BUILD_URL"'", "metrics": [
+              {"name": "image.size_bytes", "value": 81234432,
+               "labels": {"machine": "amd64", "image": "core-image"}}]}' \
+    https://revtrend.example/api/v1/projects/myproject/measurements
+```
+
+The measurement `source` (`ci` or `manual`) is derived from the token issuer,
+never from the request. Per commit, CI runs take precedence over manual runs.
+
+Each measurement records the submitter as `<issuer name>:<sub>`, the stable
+OIDC identifier. For a readable audit trail, set `display_claims` on an issuer
+(e.g. `["preferred_username", "name"]`): the first claim present in the token
+is stored as `submitted_name`.
+
+## CLI
+
+```sh
+pipx install revtrend
+export REVTREND_URL=https://revtrend.example
+
+revtrend login
+revtrend push --project myproject --sha HEAD metrics.json
+revtrend compare --project myproject --head HEAD --base release/1.0
+```
+
+`login` prints a URL to open in any browser, also from an ssh session: the
+service receives the login redirect and relays the authorization code to the
+CLI, which redeems it with its PKCE verifier. Tokens are cached in
+`~/.cache/revtrend/sessions.json` and refreshed automatically.
+`$REVTREND_TOKEN` overrides the cached session.
+
+`push` takes a JSON array of metrics (`-` reads stdin):
+
+```json
+[{"name": "image.size_bytes", "value": 81234432,
+  "labels": {"machine": "amd64", "image": "core-image"}}]
+```
+
+`--sha` and `--head` are resolved in the current repository, so backfilling
+means checking out an old commit, measuring and pushing. The commit must exist
+in the remote. The run id defaults to `manual-<user>-<timestamp>`; pass
+`--run-id` to make a retry idempotent.
+
+`compare` prints head vs. baseline per series, or the raw response with
+`--json`.
+
+## Development
+
+```sh
+uv sync
+```
+
+Tests:
+
+```sh
+uv run pytest
+```
+
+Static checks:
+
+```sh
+uv run ruff check
+uv run ruff format --check
+```
+
+Entry points:
+
+- `revtrend-server` — HTTP API (FastAPI + uvicorn)
+- `revtrend` — CLI for pushing measurements and comparing commits

revtrend-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "revtrend"
+version = "0.1.0"
+description = "Track numeric metrics per git commit and visualize trends in Grafana"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastapi",
+    "httpx",
+    "prometheus-client>=0.26.0",
+    "pydantic>=2.14.3",
+    "PyJWT[crypto]",
+    "uvicorn",
+]
+
+[[project.authors]]
+name = "Simon Holesch"
+email = "simon@holesch.de"
+
+[project.urls]
+Homepage = "https://github.com/holesch/revtrend"
+Source = "https://github.com/holesch/revtrend"
+Issues = "https://github.com/holesch/revtrend/issues"
+
+[project.scripts]
+revtrend = "revtrend.cli:main"
+revtrend-server = "revtrend.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "ruff==0.14.7",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "I",
+    "N",
+    "UP",
+    "ASYNC",
+    "S",
+    "B",
+    "A",
+    "C4",
+    "ISC",
+    "LOG",
+    "G",
+    "PIE",
+    "T20",
+    "PT",
+    "RSE",
+    "SIM",
+    "TID",
+    "ARG",
+    "PTH",
+    "PL",
+    "FLY",
+    "FURB",
+    "RUF",
+]
+ignore = [
+    "E501",
+    "PLW2901",
+    "PLR0402",
+    "PTH123",
+    "S603",
+    "SIM108",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = [
+    "PLR2004",
+    "S101",
+    "S607",
+    "ARG001",
+    "PLR0913",
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"

revtrend-0.1.0/pyproject.toml.orig

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "revtrend"
+version = "0.1.0"
+description = "Track numeric metrics per git commit and visualize trends in Grafana"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Simon Holesch", email = "simon@holesch.de" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastapi",
+    "httpx",
+    "prometheus-client>=0.26.0",
+    "pydantic>=2.14.3",
+    "PyJWT[crypto]",
+    "uvicorn",
+]
+
+[project.urls]
+Homepage = "https://github.com/holesch/revtrend"
+Source = "https://github.com/holesch/revtrend"
+Issues = "https://github.com/holesch/revtrend/issues"
+
+[project.scripts]
+revtrend = "revtrend.cli:main"
+revtrend-server = "revtrend.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "ruff==0.14.7",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff.lint]
+select = [
+    "F",      # Pyflakes
+    "E", "W", # pycodestyle
+    "I",      # isort
+    "N",      # pep8-naming
+    "UP",     # pyupgrade
+    "ASYNC",  # flake8-async
+    "S",      # flake8-bandit
+    "B",      # flake8-bugbear
+    "A",      # flake8-builtins
+    "C4",     # flake8-comprehensions
+    "ISC",    # flake8-implicit-str-concat
+    "LOG",    # flake8-logging
+    "G",      # flake8-logging-format
+    "PIE",    # flake8-pie
+    "T20",    # flake8-print
+    "PT",     # flake8-pytest-style
+    "RSE",    # flake8-raise
+    "SIM",    # flake8-simplify
+    "TID",    # flake8-tidy-imports
+    "ARG",    # flake8-unused-arguments
+    "PTH",    # flake8-use-pathlib
+    "PL",     # Pylint
+    "FLY",    # flynt
+    "FURB",   # refurb
+    "RUF",    # Ruff-specific rules
+]
+ignore = [
+    # "Line too long"
+    # -> ruff format handles code, long strings are fine
+    "E501",
+    # "for loop variable overwritten by assignment target"
+    "PLW2901",
+    # "Use `from x import y` in lieu of alias"
+    # -> style: absolute module imports only, aliased where necessary
+    "PLR0402",
+    # "open() should be replaced by Path.open()"
+    # -> creating a Path object just to open a file is overkill
+    "PTH123",
+    # "subprocess call: check for execution of untrusted input"
+    # -> false positives, git is called with argument lists
+    "S603",
+    # "Use ternary operator instead of if-else-block"
+    # -> can make the code less readable
+    "SIM108",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = [
+    # "Magic value used in comparison"
+    "PLR2004",
+    # "Use of assert detected"
+    "S101",
+    # "Starting a process with a partial executable path"
+    "S607",
+    # "Unused function argument"
+    # -> fixtures requested for their side effects
+    "ARG001",
+    # "Too many arguments in function definition"
+    "PLR0913",
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"