Build flake-lock-report Rust plugin for PR flake.lock changes #81

Open
opened 2026-11-15 10:36:58 +00:00 by martin · 0 comments
Owner

Summary

Create a Rust Woodpecker plugin, flake-lock-report, that runs on pull requests and publishes one idempotent PR comment describing changes to flake.lock. It reports only direct root inputs, prefers upstream release notes when inputs are tagged, and falls back to changelog/compare links with capped commit summaries.

Context

The workspace already has Rust plugins built with woodpecker-plugins-core, mkRustPlugin, and Forgejo API helpers (plugins/forgejo-opencode-review, plugins/forgejo-release). my-clients exposes repo_get_raw_file, repo_compare_diff, repo_list_releases, and repo_get_release_by_tag, so the base lockfile and Forgejo-hosted upstreams can be read without a full clone or a git binary.

PR pipelines often update flake.lock through Renovate or manual input bumps. Reviewers need the input-level delta and upstream context without reading the raw lock diff. The plugin is standalone and can be placed before or after a nixidy-switch step; it has no code dependency on Nixidy.

No existing issue covers this. #63 proposes PR-description updates in forgejo-opencode-review and is a different feature.

Scope

  • Add a Rust workspace member plugins/flake-lock-report with a default.nix using mkRustPlugin.
  • Resolve direct inputs from root.inputs, including follows paths; ignore transitive nodes.
  • Fetch the base flake.lock via Forgejo repo_get_raw_file at the PR base ref; read the head lockfile from the workspace.
  • Diff by root input name and report added, removed, and updated direct inputs.
  • Resolve upstream sources for GitHub, GitLab, Forgejo/Codeberg, and generic Git URLs.
  • Prefer release notes when old/new refs are tags; fall back to changelog links, then compare links with capped commit summaries.
  • Publish or update one marker comment on the PR.
  • Add settings, README, unit and wiremock tests, and a dry-run integration pipeline.
  • Version the plugin at 0.1.0.

Design

Lockfile flow

  1. Resolve the Forgejo URL/token and owner, repo, and PR number via resolve_ci_vars.
  2. Read PR metadata to get the base ref/sha.
  3. Fetch the base lockfile via repo_get_raw_file; read the head lockfile from the workspace or head_lock_path.
  4. For each configured lock_paths entry, parse both files and diff.

Direct inputs

  • root.inputs entries map names to node keys or follows arrays.
  • Resolve follow paths to their effective node; compare by root input name on the old and new sides.
  • Deduplicate names that resolve to the same node.
  • Transitive nodes are not fetched. include_indirect (default false) may list them compactly without network access.
  • type = "indirect" nodes are not fetched.

Change detection

  • updated when locked.rev differs, plus narHash/original changes.
  • added / removed when a direct input exists on only one side.
  • Handle non-rev inputs (path, tarball, indirect) by comparing locked/original fields.

Upstream enrichment order

  1. Releases when the input is tagged:
    • Detect tags from original.ref and locked.ref (refs/tags/... or bare tags; reject refs/heads/* and commit SHAs).
    • Do not paginate huge tag lists to discover a tag; fall back to compare when the lock does not record one.
    • GitHub: /repos/{owner}/{repo}/releases/tags/{tag}.
    • GitLab: /projects/{id}/releases/{tag}.
    • Forgejo/Codeberg: repo_get_release_by_tag.
    • Select releases in (old, new] by semver when both tags parse; otherwise show available releases.
    • Render release name, tag, date, link, and a truncated body excerpt.
  2. Changelog link when no release is available; probe common names via the provider contents API.
  3. Compare as the final fallback:
    • GitHub compare API, GitLab compare API, Forgejo repo_compare_diff.
    • Cap commit subjects and total output; use revCount when available to avoid huge ranges.

Comment behaviour

  • Marker: <!-- flake-lock-report -->.
  • Find the current user's existing marker comment and update it; otherwise create one.
  • If there are no changes and a marker exists, replace it with a brief "No flake.lock changes" note.
  • No comment when there is nothing to report and no existing marker.
  • dry_run renders to stdout without posting.

Safety and failure handling

  • GET-only requests over HTTPS; allowlist public forge hosts plus the configured Forgejo host.
  • Never forward the CI Forgejo token to third-party hosts; optional github_token is sent only to GitHub.
  • Timeouts, response-size limits, capped commit lists, and comment-size limits.
  • Missing flake.lock at base skips quietly; other base-fetch errors fail with an actionable message.
  • Enrichment failures degrade only the affected input; the core report still posts.

Settings

Setting Env var Default Description
forgejo_url PLUGIN_FORGEJO_URL CI_FORGEJO_URL Forgejo instance URL.
forgejo_token PLUGIN_FORGEJO_TOKEN CI_FORGEJO_TOKEN Forgejo API token.
github_token PLUGIN_GITHUB_TOKEN none Optional public GitHub API token for rate limits.
lock_paths PLUGIN_LOCK_PATHS flake.lock Comma-separated lockfile paths.
base_ref PLUGIN_BASE_REF PR base Override the PR base ref.
max_commits PLUGIN_MAX_COMMITS 10 Commit subjects per input.
max_comment_bytes PLUGIN_MAX_COMMENT_BYTES 60000 Comment size cap.
prefer_releases PLUGIN_PREFER_RELEASES true Prefer release notes over compare.
max_releases PLUGIN_MAX_RELEASES 10 Releases rendered per input.
max_release_excerpt_lines PLUGIN_MAX_RELEASE_EXCERPT_LINES 15 Release body excerpt limit.
include_indirect PLUGIN_INCLUDE_INDIRECT false Display-only compact transitive list.
include_changelog PLUGIN_INCLUDE_CHANGELOG true Probe and link changelog files.
dry_run PLUGIN_DRY_RUN false Render without posting.
base_lock_path / head_lock_path PLUGIN_* none / workspace Lockfile overrides for tests and offline runs.
allowed_hosts PLUGIN_ALLOWED_HOSTS public forge hosts Extra hosts allowed for outbound requests.

Acceptance criteria

  • plugins/flake-lock-report is a Rust workspace member and builds via mkRustPlugin as both .#flake-lock-report and .#flake-lock-report-image.
  • On a PR that changes a direct flake.lock input, the plugin posts or updates one marker comment with input name, source, old/new rev, and compare/release/changelog links.
  • Only direct root inputs are enriched. Transitive changes do not trigger upstream requests; include_indirect only affects display.
  • Tagged inputs fetch and render release notes; non-tagged inputs fall back to changelog and then compare.
  • GitHub, GitLab, Forgejo/Codeberg, and generic Git sources are handled; unsupported or private sources degrade gracefully.
  • No lockfile change produces no new comment; an existing marker comment is updated to a no-change note.
  • Re-runs update the same comment and never create duplicates.
  • Tokens are not sent to third-party hosts; output is escaped and truncated.
  • Unit and wiremock tests cover direct-input resolution, tag detection, release selection, fallbacks, and idempotent comment updates.
  • Integration pipeline runs with fixture lockfiles in dry-run mode.
  • README documents settings, provider behaviour, and an example PR workflow, including use after nixidy-switch.
  • cargo test -p flake-lock-report, cargo clippy -p flake-lock-report -- -D warnings, just lint, and nix build .#flake-lock-report pass.

Out of scope

  • Extracting and rendering full changelog sections beyond release excerpts.
  • Creating or updating the PR description; #63 covers a different feature in forgejo-opencode-review.
  • Private upstream authentication beyond the optional GitHub token.
  • Coupling to the nixidy-switch plugin implementation.

Dependencies

  • None. Related: #63 proposes PR-description updates in forgejo-opencode-review; this plugin posts a dedicated comment and does not depend on it.
  • Uses my-clients Forgejo endpoints already used by forgejo-release and forgejo-opencode-review.

Phases

  1. Scaffold, direct-input diff, Forgejo base fetch, marker comment, dry-run.
  2. GitHub release/compare enrichment.
  3. GitLab and Forgejo/Codeberg release/compare enrichment.
  4. Tests, README, integration coverage, release 0.1.0.
## Summary Create a Rust Woodpecker plugin, `flake-lock-report`, that runs on pull requests and publishes one idempotent PR comment describing changes to `flake.lock`. It reports only direct root inputs, prefers upstream release notes when inputs are tagged, and falls back to changelog/compare links with capped commit summaries. ## Context The workspace already has Rust plugins built with `woodpecker-plugins-core`, `mkRustPlugin`, and Forgejo API helpers (`plugins/forgejo-opencode-review`, `plugins/forgejo-release`). `my-clients` exposes `repo_get_raw_file`, `repo_compare_diff`, `repo_list_releases`, and `repo_get_release_by_tag`, so the base lockfile and Forgejo-hosted upstreams can be read without a full clone or a `git` binary. PR pipelines often update `flake.lock` through Renovate or manual input bumps. Reviewers need the input-level delta and upstream context without reading the raw lock diff. The plugin is standalone and can be placed before or after a `nixidy-switch` step; it has no code dependency on Nixidy. No existing issue covers this. #63 proposes PR-description updates in `forgejo-opencode-review` and is a different feature. ## Scope - Add a Rust workspace member `plugins/flake-lock-report` with a `default.nix` using `mkRustPlugin`. - Resolve direct inputs from `root.inputs`, including `follows` paths; ignore transitive nodes. - Fetch the base `flake.lock` via Forgejo `repo_get_raw_file` at the PR base ref; read the head lockfile from the workspace. - Diff by root input name and report added, removed, and updated direct inputs. - Resolve upstream sources for GitHub, GitLab, Forgejo/Codeberg, and generic Git URLs. - Prefer release notes when old/new refs are tags; fall back to changelog links, then compare links with capped commit summaries. - Publish or update one marker comment on the PR. - Add settings, README, unit and wiremock tests, and a dry-run integration pipeline. - Version the plugin at `0.1.0`. ## Design ### Lockfile flow 1. Resolve the Forgejo URL/token and owner, repo, and PR number via `resolve_ci_vars`. 2. Read PR metadata to get the base ref/sha. 3. Fetch the base lockfile via `repo_get_raw_file`; read the head lockfile from the workspace or `head_lock_path`. 4. For each configured `lock_paths` entry, parse both files and diff. ### Direct inputs - `root.inputs` entries map names to node keys or `follows` arrays. - Resolve follow paths to their effective node; compare by root input name on the old and new sides. - Deduplicate names that resolve to the same node. - Transitive nodes are not fetched. `include_indirect` (default `false`) may list them compactly without network access. - `type = "indirect"` nodes are not fetched. ### Change detection - `updated` when `locked.rev` differs, plus `narHash`/`original` changes. - `added` / `removed` when a direct input exists on only one side. - Handle non-rev inputs (`path`, `tarball`, `indirect`) by comparing `locked`/`original` fields. ### Upstream enrichment order 1. **Releases** when the input is tagged: - Detect tags from `original.ref` and `locked.ref` (`refs/tags/...` or bare tags; reject `refs/heads/*` and commit SHAs). - Do not paginate huge tag lists to discover a tag; fall back to compare when the lock does not record one. - GitHub: `/repos/{owner}/{repo}/releases/tags/{tag}`. - GitLab: `/projects/{id}/releases/{tag}`. - Forgejo/Codeberg: `repo_get_release_by_tag`. - Select releases in `(old, new]` by semver when both tags parse; otherwise show available releases. - Render release name, tag, date, link, and a truncated body excerpt. 2. **Changelog link** when no release is available; probe common names via the provider contents API. 3. **Compare** as the final fallback: - GitHub compare API, GitLab compare API, Forgejo `repo_compare_diff`. - Cap commit subjects and total output; use `revCount` when available to avoid huge ranges. ### Comment behaviour - Marker: `<!-- flake-lock-report -->`. - Find the current user's existing marker comment and update it; otherwise create one. - If there are no changes and a marker exists, replace it with a brief "No flake.lock changes" note. - No comment when there is nothing to report and no existing marker. - `dry_run` renders to stdout without posting. ### Safety and failure handling - GET-only requests over HTTPS; allowlist public forge hosts plus the configured Forgejo host. - Never forward the CI Forgejo token to third-party hosts; optional `github_token` is sent only to GitHub. - Timeouts, response-size limits, capped commit lists, and comment-size limits. - Missing `flake.lock` at base skips quietly; other base-fetch errors fail with an actionable message. - Enrichment failures degrade only the affected input; the core report still posts. ## Settings | Setting | Env var | Default | Description | | --- | --- | --- | --- | | `forgejo_url` | `PLUGIN_FORGEJO_URL` | `CI_FORGEJO_URL` | Forgejo instance URL. | | `forgejo_token` | `PLUGIN_FORGEJO_TOKEN` | `CI_FORGEJO_TOKEN` | Forgejo API token. | | `github_token` | `PLUGIN_GITHUB_TOKEN` | none | Optional public GitHub API token for rate limits. | | `lock_paths` | `PLUGIN_LOCK_PATHS` | `flake.lock` | Comma-separated lockfile paths. | | `base_ref` | `PLUGIN_BASE_REF` | PR base | Override the PR base ref. | | `max_commits` | `PLUGIN_MAX_COMMITS` | `10` | Commit subjects per input. | | `max_comment_bytes` | `PLUGIN_MAX_COMMENT_BYTES` | `60000` | Comment size cap. | | `prefer_releases` | `PLUGIN_PREFER_RELEASES` | `true` | Prefer release notes over compare. | | `max_releases` | `PLUGIN_MAX_RELEASES` | `10` | Releases rendered per input. | | `max_release_excerpt_lines` | `PLUGIN_MAX_RELEASE_EXCERPT_LINES` | `15` | Release body excerpt limit. | | `include_indirect` | `PLUGIN_INCLUDE_INDIRECT` | `false` | Display-only compact transitive list. | | `include_changelog` | `PLUGIN_INCLUDE_CHANGELOG` | `true` | Probe and link changelog files. | | `dry_run` | `PLUGIN_DRY_RUN` | `false` | Render without posting. | | `base_lock_path` / `head_lock_path` | `PLUGIN_*` | none / workspace | Lockfile overrides for tests and offline runs. | | `allowed_hosts` | `PLUGIN_ALLOWED_HOSTS` | public forge hosts | Extra hosts allowed for outbound requests. | ## Acceptance criteria - [ ] `plugins/flake-lock-report` is a Rust workspace member and builds via `mkRustPlugin` as both `.#flake-lock-report` and `.#flake-lock-report-image`. - [ ] On a PR that changes a direct `flake.lock` input, the plugin posts or updates one marker comment with input name, source, old/new rev, and compare/release/changelog links. - [ ] Only direct root inputs are enriched. Transitive changes do not trigger upstream requests; `include_indirect` only affects display. - [ ] Tagged inputs fetch and render release notes; non-tagged inputs fall back to changelog and then compare. - [ ] GitHub, GitLab, Forgejo/Codeberg, and generic Git sources are handled; unsupported or private sources degrade gracefully. - [ ] No lockfile change produces no new comment; an existing marker comment is updated to a no-change note. - [ ] Re-runs update the same comment and never create duplicates. - [ ] Tokens are not sent to third-party hosts; output is escaped and truncated. - [ ] Unit and wiremock tests cover direct-input resolution, tag detection, release selection, fallbacks, and idempotent comment updates. - [ ] Integration pipeline runs with fixture lockfiles in dry-run mode. - [ ] README documents settings, provider behaviour, and an example PR workflow, including use after `nixidy-switch`. - [ ] `cargo test -p flake-lock-report`, `cargo clippy -p flake-lock-report -- -D warnings`, `just lint`, and `nix build .#flake-lock-report` pass. ## Out of scope - Extracting and rendering full changelog sections beyond release excerpts. - Creating or updating the PR description; #63 covers a different feature in `forgejo-opencode-review`. - Private upstream authentication beyond the optional GitHub token. - Coupling to the `nixidy-switch` plugin implementation. ## Dependencies - None. Related: #63 proposes PR-description updates in `forgejo-opencode-review`; this plugin posts a dedicated comment and does not depend on it. - Uses `my-clients` Forgejo endpoints already used by `forgejo-release` and `forgejo-opencode-review`. ## Phases 1. Scaffold, direct-input diff, Forgejo base fetch, marker comment, dry-run. 2. GitHub release/compare enrichment. 3. GitLab and Forgejo/Codeberg release/compare enrichment. 4. Tests, README, integration coverage, release `0.1.0`.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/woodpecker-plugins#81
No description provided.