Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
8 changes: 4 additions & 4 deletions .agents/agents/fw-compat-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: >
Use before pushing anything that edits `rust-modules/base/src/dynlib.rs`,
`rust-modules/media-codecs/src/ffi.rs`, `rust-modules/media-codecs/src/venc.rs`,
`rust-modules/net/src/net.rs`, `rust-modules/net/src/curlio.rs`,
`src/starfish.c`, `src/video_plane.c`, `src/starfish.h`, `rust-modules/platform/src/webos/ls2/uri.rs`,
`src/starfish.c`, `src/video_plane.c`, `src/starfish.h`, `rust-modules/os/src/webos/ls2/uri.rs`,
`rust-modules/play-uri/src`, `ci/expected-dt-needed.txt`,
`ci/expected-dt-needed-uri.txt`, the Makefile's `LIBS_REAL`, `PLAYBACK_BACKENDS` or
`PLAYBACK_HAS_FEED`, or that adds any
Expand Down Expand Up @@ -57,7 +57,7 @@ In scope if the diff touches any of:
| `rust-modules/net/src/curlio.rs` | the byte-range `curl_multi_*` `dynlib!` table, exposed as `net::range_io` |
| `src/starfish.c` | 15 mangled C++ externs against real libraries (built only when `PLAYBACK_HAS_FEED`) |
| `src/video_plane.c`, `src/starfish.h` | the video-plane binding: its own `dlopen` of ACB, the `dlsym` probe for the SDL exported window, and `vp_mode()` choosing between them; the header declares the `acb_*` / `sf_*` seam the Rust externs mirror |
| `rust-modules/platform/src/webos/ls2/uri.rs` and the `LSCall` declaration in `webos.rs` | the `com.webos.media` LS2 worker; `LSCall` is a hard import of `libluna-service2` in every build with the platform feature `uri-transport`, which the application's `play-uri` feature (in the shipping set) turns on |
| `rust-modules/os/src/webos/ls2/uri.rs` and the `LSCall` declaration in `webos.rs` | the `com.webos.media` LS2 worker; `LSCall` is a hard import of `libluna-service2` in every build with the os crate's feature `uri-transport`, which the application's `play-uri` feature (in the shipping set) turns on |
| `rust-modules/play-uri/src` | the URI backend declares no `extern "C"` of its own: it reaches ACB through `DisplaySink` (the platform's `acb_*` externs) and the bus through `tv::uri::UriMedia`; a declaration appearing here is a new undefined symbol and a layer violation |
| any new `extern "C"` block, `#[link]`, or `__asm__("<mangled>")` declaration | each one adds an undefined symbol, or a whole `DT_NEEDED` entry |
| `Makefile`'s `LIBS_REAL` and the link rule that uses it | a new `-l` is a new hard `DT_NEEDED` |
Expand Down Expand Up @@ -163,9 +163,9 @@ grade an ELF at all.
git -C <repo> diff --stat HEAD # or the range under review
git -C <repo> diff HEAD -- rust-modules/base/src/dynlib.rs rust-modules/media-codecs/src/ffi.rs rust-modules/media-codecs/src/venc.rs \
rust-modules/net/src/net.rs rust-modules/net/src/curlio.rs src/starfish.c src/video_plane.c src/starfish.h \
rust-modules/platform/src/webos.rs rust-modules/platform/src/webos/ls2/uri.rs Makefile \
rust-modules/os/src/webos.rs rust-modules/os/src/webos/ls2/uri.rs Makefile \
ci/expected-dt-needed.txt ci/expected-dt-needed-uri.txt
grep -rn '#\[link\|extern "C"\|__asm__("' rust-modules/src rust-modules/media/src rust-modules/play-feed/src rust-modules/play-uri/src rust-modules/platform/src rust-modules/media-codecs/src rust-modules/net/src src # against the diff, not the tree
grep -rn '#\[link\|extern "C"\|__asm__("' rust-modules/src rust-modules/media/src rust-modules/play-feed/src rust-modules/play-uri/src rust-modules/os/src rust-modules/media-codecs/src rust-modules/net/src src # against the diff, not the tree
```

### 1. Decide, out loud, whether you are grading an ELF or grading source
Expand Down
146 changes: 146 additions & 0 deletions .agents/skills/review-pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
---
name: review-pr
description: >
Review someone's pull request locally and post the review from the owner's own GitHub account,
after the owner has read the draft: "review #N", "review this PR", "check PR N", "what do you
think of #N", "post a review on N", "final review", and any external contributor's PR. Reads the
whole conversation and CI first, analyses with the repo's `pr-reviewer` agent (plus the tests and
`fw-compat-reviewer` when the diff needs them), drafts in a low-noise maintainer style (`lgtm`
or a short numbered list, findings inline), and posts one formal GitHub review only on the
owner's click. Use it instead of the `@claude` GitHub bot when the PR is from a fork and matters,
when tests have to run, or when the review should be the owner's. For a review of your OWN branch
before opening a PR, run `pr-reviewer` directly; this skill is for reviewing a PR that exists.
---

# review-pr: a local review, posted as the owner

The workflow and the writing rules follow umputun's review skill
([umputun/cc-thingz](https://github.com/umputun/cc-thingz), `plugins/review`), chosen by the owner
because it knows about bot noise. The analysis is this repo's own: `pr-reviewer` reviews against
AGENTS.md's working rules (read from the base), `docs/review-checklist.md` and the module guides,
and `tools/review-eval.py` grades it against past PRs whose bugs are known. Do not replace it with a
generic reviewer prompt; a change to it is measured with `review-eval.py` first.

The `@claude` bot (`.github/workflows/claude.yml`) is the quick first pass on every thread. This
skill is the deep one: it can run tests and the repo's reviewers, and its review counts as the owner's.

## 1. Context, before reading any code

```bash
gh pr view N --json number,title,body,author,state,isDraft,baseRefName,headRefName,headRefOid,\
headRepositoryOwner,isCrossRepository,additions,deletions,changedFiles,files,mergeable,mergeStateStatus
gh api repos/{owner}/{repo}/issues/N/comments --jq '.[] | "[\(.user.login)] \(.body)"'
gh api repos/{owner}/{repo}/pulls/N/comments --jq '.[] | "[\(.user.login) on \(.path):\(.line // .original_line)] \(.body)"'
gh api repos/{owner}/{repo}/pulls/N/reviews --jq '.[] | "[\(.user.login) - \(.state)] \(.body)"'
gh pr checks N
```

Summarize for yourself: what is already resolved, what is still open, what the OWNER already said
(never repeat it), and what bots found (Copilot, the `@claude` bot, Codex). A bot finding goes into
the draft only after you have checked it in the code. A CONFLICTING or BEHIND PR explains odd
"deletions" in the diff; say so early.

Then ask the owner once (AskUserQuestion): **Full** (worktree, `pr-reviewer`, tests when allowed)
or **Quick** (diff only). Quick skips to step 4 with what `gh pr diff N` shows.

## 2. Worktree (never switch any checkout's branch)

```bash
git fetch origin "pull/N/head:refs/remotes/pr/N" && git fetch origin main
git worktree add --detach ".claude/worktrees/review-N" "refs/remotes/pr/N"
```

`gh pr checkout` moves a checkout's branch: do not use it. The worktree goes away in step 6.

## 3. Analysis

**`pr-reviewer`** (Agent tool, `subagent_type: pr-reviewer`), on `origin/main...refs/remotes/pr/N`,
run from the worktree. Hand it the context from step 1 (resolved points, the owner's earlier
comments, open questions) so it does not re-raise them. Its findings carry `file:line`, a severity
and a fix; keep the full head SHA its report names.

**`fw-compat-reviewer`** too when `pr-reviewer` recommends it (FFI, linkage, `dynlib!`, Starfish,
ACB, curl, FFmpeg).

**Tests: who wrote the code decides.**

- The author has write access (`gh api repos/{owner}/{repo}/collaborators/AUTHOR/permission`):
pick the tier with the `which-tier` skill and run it in the worktree (`make test-crate C=...`,
`make test-hostsim ...`). Never `make check` in the foreground; it can queue for a long time.
- An outside contributor (a fork, no write access): running their tests runs THEIR code on this
Mac, next to the owner's tokens, `~/.config/plxnative/` and the TV. Read CI's results instead
(`gh pr checks N`; a fork's CI holds no secrets). Run anything locally only after you have read
every changed build input (`build.rs`, `Makefile`, `Cargo.toml`, `ci/`, `tests/`, `tools/`, any
script the tests call) and the owner has said yes for this PR.

**Also judge**, as umputun's skill does: over-engineering (name the simpler thing), code that does
not match the patterns around it (AGENTS.md rule 1: a shared mechanism exists), and scope creep.
Sort every file as core, supporting, related cleanup or unrelated; unrelated and risky is a finding,
an unrelated lint fix is not.

Show the owner the condensed findings, then ask each open design question one at a time before
drafting. Their answer goes into the draft as their decision.

## 4. The draft

Findings that sit on a line become **inline comments**, one or two sentences each, with a
`suggestion` block when the fix is small and certain. The **body** is:

- `lgtm` when nothing is wrong, or
- a short numbered list of what is not tied to a line (failing CI, a question, scope creep), each
with `file:line`, then at most one closing line (`otherwise looks good`).

Writing rules (umputun's `writing-style`): casual, lowercase is fine, direct; state an opinion
instead of hedging, say "not sure" when you are not. Never restate what the PR does: the author
knows. No headings, no praise, no "great work", no sign-off, no "let me know". None of:
comprehensive, robust, leverage, utilize, facilitate, seamless, "it's worth noting", "in order to",
"additionally", "furthermore". Code in a suggestion handles its errors. Severity words (BLOCKER,
MAJOR) stay out of the comment; a real bug reads as one plainly ("this accepts `wss://v1/ws`").

Show the whole draft (body and each inline comment with its `path:line`) as one text block, then
ask (AskUserQuestion): **Comment** / **Request changes** / **Approve** / **Edit** / **Cancel**.
Nothing is posted without that answer, every time: a review on someone's PR is the owner speaking.

## 5. Post one review

One formal review, the inline comments attached, pinned to the commit that was reviewed. Write it
to a file and send it; never put the text on the command line.

```bash
cat > "$TMPDIR/review-N.json" <<'JSON'
{
"commit_id": "<the full head SHA pr-reviewer read>",
"event": "COMMENT",
"body": "<body>",
"comments": [
{"path": "rust-modules/owp/src/relays.rs", "line": 32, "side": "RIGHT", "body": "<comment>"}
]
}
JSON
gh api -X POST "repos/{owner}/{repo}/pulls/N/reviews" --input "$TMPDIR/review-N.json"
```

`event` is `COMMENT`, `REQUEST_CHANGES` or `APPROVE` as the owner chose. A `line` must be in the
diff on that side, or GitHub refuses the whole review (422); move such a comment into the body.
The head moved since the review (`gh pr view N --json headRefOid`): say so and re-review, do not
post findings about code that is no longer there. The repo is public: never quote a value from a
gitignored private file (AGENTS.md); outbound-guard scans the file too.

Record what `pr-reviewer` found on that SHA, so the landing gate reads it:

```bash
tools/pr-land.py reviewed N --sha <SHA> --blockers B --majors M --minors K
```

An **Approve** is not a merge. Landing goes through the `land-pr` skill (`tools/pr-land.py`,
squash only) and needs the owner's authorization to merge, which an approval is not.

## 6. Clean up

```bash
git worktree remove ".claude/worktrees/review-N" && git update-ref -d "refs/remotes/pr/N"
```

Do it after the review is posted or cancelled, not before: follow-up questions need the worktree.
A worktree with build output in it (a test run) goes with `git worktree remove --force` only after
`git -C .claude/worktrees/review-N status --short` shows nothing but ignored files.
4 changes: 2 additions & 2 deletions .agents/skills/which-tier/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ but a photograph could show it (`gfx.rs`, at the `glBlendFuncSeparate` call).

### Tier 1 — `make check`

`cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_platform -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens`, preceded by `make lint` (three **named** clippy lints —
`cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_owp`, preceded by `make lint` (three **named** clippy lints —
`ifs_same_cond`, `same_functions_in_if_condition`, `if_same_then_else` — the shadowed-branch gate),
and followed by **three** host checks that are easy to forget are in here: `python3 ci/flavor.py
--selftest` (the flavour transform, whose central assertion is that the STABLE transform is the
Expand Down Expand Up @@ -114,7 +114,7 @@ lock.) Do not write a new number here: measure it if you need one — this file
Count it yourself if you need the number:

```sh
cd rust-modules && cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_platform -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -- --list | grep -c ': test'
cd rust-modules && cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_owp -- --list | grep -c ': test'
```

**Run it on the pinned toolchain.** `make check` uses `cargo +$(RUST_TOOLCHAIN)`, the `channel` of
Expand Down
2 changes: 1 addition & 1 deletion .claude/hooks/release-config-check-test.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ def edit(path, tool="Edit", key="file_path", **extra):
(FIRE, "Write", edit("/repo/rust-modules/src/dev.rs", tool="Write"), ROOT),
(FIRE, "a layer crate's source", edit("/repo/rust-modules/base/src/paths.rs"), ROOT),
(FIRE, "the machine layer crate's source", edit("/repo/rust-modules/machine/src/idle.rs"), ROOT),
(FIRE, "the platform layer crate's source", edit("/repo/rust-modules/platform/src/webos.rs"), ROOT),
(FIRE, "the os layer crate's source", edit("/repo/rust-modules/os/src/webos.rs"), ROOT),
(FIRE, "the gfx layer crate's source", edit("/repo/rust-modules/gfx/src/gfx.rs"), ROOT),
(FIRE, "the net layer crate's source", edit("/repo/rust-modules/net/src/net.rs"), ROOT),
(FIRE, "the ui layer crate's source", edit("/repo/rust-modules/ui/src/widgets.rs"), ROOT),
Expand Down
2 changes: 1 addition & 1 deletion .claude/hooks/release-config-check.py
Original file line number Diff line number Diff line change
Expand Up @@ -273,7 +273,7 @@ def rust_src_target(payload, root, cwd=None):
src = os.path.realpath(os.path.join(root, "rust-modules", "src"))
# The layer crates split out of `src` (docs/module-layers.md) are compiled by the same
# `cargo check --lib` as a dependency, so an edit there is a release-configuration risk too.
layer_srcs = [os.path.realpath(os.path.join(root, "rust-modules", layer, "src")) for layer in ("base", "machine", "net", "platform", "gfx", "ui", "plex", "telemetry", "data", "session", "media", "appkit", "screens")]
layer_srcs = [os.path.realpath(os.path.join(root, "rust-modules", layer, "src")) for layer in ("base", "machine", "net", "os", "gfx", "ui", "plex", "telemetry", "data", "session", "media", "appkit", "screens")]
if not any(path.startswith(s + os.sep) for s in [src] + layer_srcs):
return None
# `--lib` compiles no bin target, and `sim.rs` needs `hostsim`, which the release set never has.
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ jobs:
# (`cargo metadata` resolves; it compiles nothing), plus an informational line count.
# The binary-size budget runs in cross-build, where the binary exists. Limits and how to
# raise one deliberately: ci/build-budgets.json, docs/agent-reference.md.
run: python3 ci/check-build-budgets.py --graph --src rust-modules/src --src rust-modules/base/src --src rust-modules/machine/src --src rust-modules/net/src --src rust-modules/platform/src --src rust-modules/gfx/src --src rust-modules/ui/src --src rust-modules/plex/src --src rust-modules/telemetry/src --src rust-modules/data/src --src rust-modules/session/src --src rust-modules/media/src --src rust-modules/playback-contract/src --src rust-modules/media-codecs/src --src rust-modules/play-feed/src --src rust-modules/play-uri/src --src rust-modules/appkit/src --src rust-modules/screens/src
run: python3 ci/check-build-budgets.py --graph --src rust-modules/src --src rust-modules/base/src --src rust-modules/machine/src --src rust-modules/net/src --src rust-modules/os/src --src rust-modules/gfx/src --src rust-modules/ui/src --src rust-modules/plex/src --src rust-modules/telemetry/src --src rust-modules/data/src --src rust-modules/session/src --src rust-modules/media/src --src rust-modules/playback-contract/src --src rust-modules/media-codecs/src --src rust-modules/play-feed/src --src rust-modules/play-uri/src --src rust-modules/appkit/src --src rust-modules/screens/src --src rust-modules/owp/src

- name: Third-party notices vs the ARM runtime graph
# `make check` runs only the OFFLINE half of this (ci/gen-third-party-notices.py --check), which
Expand Down Expand Up @@ -309,7 +309,7 @@ jobs:
# for plxnative-modules both ways), so the `cargo test --lib` below finds everything built
# and this step is where the compile happens, not an extra one. The upload below carries it.
shell: bash
run: cd rust-modules && cargo "+$RUST_TOOLCHAIN" test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_platform -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens --no-run --timings
run: cd rust-modules && cargo "+$RUST_TOOLCHAIN" test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_owp --no-run --timings

- name: make check-cargo-unit-default
# Teed to a file so the size step below can read the `test result:` lines this run already
Expand Down
Loading
Loading