From a979890f1d3af0d02d4f48955385627cf8d2a094 Mon Sep 17 00:00:00 2001 From: Andy Horn Date: Tue, 3 Nov 2026 08:29:44 -0700 Subject: [PATCH 1/3] feat: support pull requests without a local clone Detect a checkout only when origin matches the target repository, and otherwise reach the pull request through gh -R and the GitHub API: the diff from gh pr diff, and each changed file by blob sha from the paginated pull request files endpoint. Align the README requirements and add an end-to-end eval for the no-clone path. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01T58NPz2J74Vkr1ABminq2L --- README.md | 4 +- evals/full/explain-pr-no-clone/case.yaml | 4 + evals/full/explain-pr-no-clone/fixture.sh | 6 + .../graders/no-shortened-paths.md | 6 + .../graders/no-template-placeholders.md | 6 + .../graders/page-copied.md | 4 + .../graders/provenance-names-pr.md | 5 + .../graders/references-linked.md | 5 + .../graders/skill-fired.md | 5 + evals/full/explain-pr-no-clone/prompt.md | 16 +++ skills/explain-diff-html/SKILL.md | 122 +++++++++++++++++- 11 files changed, 177 insertions(+), 6 deletions(-) create mode 100644 evals/full/explain-pr-no-clone/case.yaml create mode 100755 evals/full/explain-pr-no-clone/fixture.sh create mode 100644 evals/full/explain-pr-no-clone/graders/no-shortened-paths.md create mode 100644 evals/full/explain-pr-no-clone/graders/no-template-placeholders.md create mode 100644 evals/full/explain-pr-no-clone/graders/page-copied.md create mode 100644 evals/full/explain-pr-no-clone/graders/provenance-names-pr.md create mode 100644 evals/full/explain-pr-no-clone/graders/references-linked.md create mode 100644 evals/full/explain-pr-no-clone/graders/skill-fired.md create mode 100644 evals/full/explain-pr-no-clone/prompt.md diff --git a/README.md b/README.md index e0244e5..696be21 100644 --- a/README.md +++ b/README.md @@ -188,8 +188,8 @@ tests the prose against the skill's writing rules. | Tool | Needed when | Used for | | ------ | ---------------------------------------- | -------------------------------------------------------------------------- | -| `git` | Every run | Resolving the base, fetching the ref, reading the diff | -| `gh` | Explaining a pull request | Fetching the pull request title, body, and URL | +| `git` | Reading from a local clone | Resolving the base, fetching the ref, reading the diff | +| `gh` | Explaining a pull request | Fetching the pull request data; with no clone, also the diff and files | | `node` | Every run, version 22.18 or later | Validating the page in step 7, and Mermaid sources in step 4 through `npx` | `gh` must be authenticated, not only installed. Check with `gh auth status`. diff --git a/evals/full/explain-pr-no-clone/case.yaml b/evals/full/explain-pr-no-clone/case.yaml new file mode 100644 index 0000000..038857b --- /dev/null +++ b/evals/full/explain-pr-no-clone/case.yaml @@ -0,0 +1,4 @@ +schema_version: "1.1" +name: explain-pr-no-clone +context: + scaffold_script: fixture.sh diff --git a/evals/full/explain-pr-no-clone/fixture.sh b/evals/full/explain-pr-no-clone/fixture.sh new file mode 100755 index 0000000..4a16ff6 --- /dev/null +++ b/evals/full/explain-pr-no-clone/fixture.sh @@ -0,0 +1,6 @@ +#!/bin/bash +# The workspace stays empty and is not a git checkout, so the skill must take +# the no-clone path. It needs an authenticated gh to reach the repository. +set -e +gh auth status >/dev/null +! git rev-parse --git-dir >/dev/null 2>&1 diff --git a/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md b/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md new file mode 100644 index 0000000..21d3bb7 --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md @@ -0,0 +1,6 @@ +--- +type: regex +target: { source: file, path: page.html } +pattern: '(class="filename"|)[^<]*\.\.\./' +match: not_contains +--- diff --git a/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md b/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md new file mode 100644 index 0000000..c59d2e0 --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md @@ -0,0 +1,6 @@ +--- +type: regex +target: { source: file, path: page.html } +pattern: 'FILL:' +match: not_contains +--- diff --git a/evals/full/explain-pr-no-clone/graders/page-copied.md b/evals/full/explain-pr-no-clone/graders/page-copied.md new file mode 100644 index 0000000..ed36721 --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/page-copied.md @@ -0,0 +1,4 @@ +--- +type: file_exists +path: page.html +--- diff --git a/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md b/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md new file mode 100644 index 0000000..59996d3 --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md @@ -0,0 +1,5 @@ +--- +type: regex +target: { source: file, path: page.html } +pattern: 'class="provenance"[\s\S]{0,400}?PR 9' +--- diff --git a/evals/full/explain-pr-no-clone/graders/references-linked.md b/evals/full/explain-pr-no-clone/graders/references-linked.md new file mode 100644 index 0000000..bad8f20 --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/references-linked.md @@ -0,0 +1,5 @@ +--- +type: regex +target: { source: file, path: page.html } +pattern: 'References link to this commit\.' +--- diff --git a/evals/full/explain-pr-no-clone/graders/skill-fired.md b/evals/full/explain-pr-no-clone/graders/skill-fired.md new file mode 100644 index 0000000..be7cc8c --- /dev/null +++ b/evals/full/explain-pr-no-clone/graders/skill-fired.md @@ -0,0 +1,5 @@ +--- +type: tool_used +tool: Skill +input_match: '"skill"\s*:\s*"(?:[\w-]+:)?explain-diff-html"' +--- diff --git a/evals/full/explain-pr-no-clone/prompt.md b/evals/full/explain-pr-no-clone/prompt.md new file mode 100644 index 0000000..1234ffd --- /dev/null +++ b/evals/full/explain-pr-no-clone/prompt.md @@ -0,0 +1,16 @@ +--- +tags: [full] +max_turns: 150 +timeout_seconds: 1800 +# allowed_tools only picks read-only tools. The run also needs Bash and Write, +# which only the CLI can grant: claude plugin eval . --allow-tools Write Bash +allowed_tools: [Read, Glob, Grep, Skill, Agent, TodoWrite] +runs: 1 +description: One end-to-end run against a real pull request from a workspace with no git checkout, graded on the produced page. +--- + +Explain https://github.com/malav2110/explain-diff-html/pull/9 as a +self-contained HTML page I can read to learn what changed and why. This +directory is not a clone of that repository. When the page is finished, also +copy it to `./page.html` in this directory so I can find it. If the home folder +is not writable here, write the page into this directory instead. diff --git a/skills/explain-diff-html/SKILL.md b/skills/explain-diff-html/SKILL.md index 4102d14..f2f8dd0 100644 --- a/skills/explain-diff-html/SKILL.md +++ b/skills/explain-diff-html/SKILL.md @@ -39,14 +39,14 @@ Continue when the work still happens another way, and say what was weaker. | Tool | Needed when | Used for | | ------ | ---------------------------------------- | -------------------------------------------------------------------------- | -| `git` | Every run | Resolving the base, fetching the ref, reading the diff | -| `gh` | Explaining a pull request | Fetching the pull request title, body, and URL | +| `git` | Reading from a local clone | Resolving the base, fetching the ref, reading the diff | +| `gh` | Explaining a pull request | Fetching the pull request data; with no clone, also the diff and files | | `node` | Every run, version 22.18 or later | Validating the page in step 7, and Mermaid sources in step 4 through `npx` | Verify them up front: ```bash -command -v git >/dev/null || echo "git is required" +command -v git >/dev/null || echo "git is required for local clones" node -e 'const [major, minor] = process.versions.node.split(".").map(Number); process.exit(major > 22 || (major === 22 && minor >= 18) ? 0 : 1)' 2>/dev/null || echo "node 22.18 or later is required" @@ -90,7 +90,9 @@ Three details this table hides: - `gh` must be authenticated, not merely installed. `gh auth status` is the check. Without `gh` the skill still explains a branch or a commit range; it cannot reach a pull request body, which is usually where the why lives. Say - on the page that the body was not read. + on the page that the body was not read. When a local clone is present, `gh` + is optional but recommended. Without a clone, `gh` is required for pull + request access. - `node` is a build-time validator only. The reader's browser loads Mermaid from the CDN, so nobody needs Node to open the finished page. - `npx -y` downloads the pinned validator on first use and caches it, so the @@ -110,6 +112,44 @@ be. A run whose change warrants none of those four shapes needs no Mermaid. The hand-built families cover it. Step 7 still needs Node to run the validator. +### Local clone vs. no clone + +The skill has two paths for explaining a pull request. + +**With a local clone** (the default path): the skill runs inside a git checkout, +uses `git fetch` and `gh pr view` to resolve the PR, and reads changed files +from the working tree. + +**Without a local clone**: the skill uses `gh pr view` with the `-R owner/repo` +flag to reach a repository you haven't cloned, and the GitHub API to +fetch file contents at the PR's head commit. This path requires `gh` to be +authenticated and a PR number or URL as the target. + +Both paths produce the same output format and honor the same output contract. +The only differences are how the skill resolves the target and gathers file +contents. + +Detect which path to use. A checkout only counts when it is the repository that +owns the pull request, so compare `origin` with the `owner/repo` parsed from the +target. Set `target_slug` to that value in lowercase, or leave it empty when the +target is a bare number, a branch, or a commit: + +```bash +in_repo=false +if command -v git >/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then + in_repo=true + origin_slug="$(git remote get-url origin 2>/dev/null | + sed -E 's#^(git@[^:]+:|[a-z+]+://[^/]+/)##; s#\.git$##' | tr '[:upper:]' '[:lower:]')" + if [ -n "$target_slug" ] && [ "$origin_slug" != "$target_slug" ]; then + in_repo=false + fi +fi +``` + +The rest of this step explains the clone path. The no-clone path follows the +same target-selection rules but replaces `git` and working-tree reads with `gh` +and the GitHub API. + ## Output contract - One self-contained HTML file. All CSS and JavaScript inline. Hand-built @@ -261,6 +301,72 @@ works. The git form above still asks `gh` for the base commit, so it does not replace `gh`. Without `gh`, ask the user which commit the pull request is based on rather than guessing one. +#### No-clone path (for pull requests only, without a local git checkout) + +Use this path when `in_repo` is false and the target is a pull request. Without +a checkout, `gh` reaches the repository through `-R owner/repo` and the GitHub +API supplies the file contents. A branch, a commit range, or a single commit has +no recorded base to resolve without a clone, so for those stop and tell the user +to run from a checkout of the repository. + +1. **Parse the target** into `owner`, `repo`, and the number ``. From + `https://github.com/owner/repo/pull/123` or `owner/repo#123`, take all three. + From a bare number there is no repository to resolve, so ask the user for it. + +2. **Create the work directory** and write its path out for later steps, as the + clone path does: + + ```bash + work="$(mktemp -d)" + echo "$work" + ``` + +3. **Fetch the metadata** with the repository named: + + ```bash + gh pr view -R owner/repo --json title,body,url,headRefName,headRefOid,baseRefName + ``` + + `headRefOid` is the head commit. Resolve every `file:line` anchor against it, + use its short form in the provenance line, and keep the full 40 characters + for the links. Take the link host from the `url` returned here. + +4. **Fetch the diff** into the work directory, using the path from step 2: + + ```bash + gh pr diff -R owner/repo > /diff.txt + [ -s /diff.txt ] || echo "STOP: the diff is empty; resolve the base before drafting" + ``` + +5. **Store each changed file** as it stands at the head. List the files from the + paginated pull request files endpoint rather than from `gh pr view`, which + stops at 100. A file the pull request deleted has no head version, so the + filter skips it. Each file is read by blob sha, so no path needs URL-encoding, + and the raw media type returns the bytes without the 1 MB cap of the Contents + API. Do not name the loop variable `path`: in zsh it is tied to `PATH`. + + ```bash + work= + gh api "repos/owner/repo/pulls//files" --paginate \ + --jq '.[] | select(.status != "removed") | [.sha, .filename] | @tsv' | + while IFS=$'\t' read -r blob changed; do + mkdir -p "$work/files/$(dirname "$changed")" && + gh api -H "Accept: application/vnd.github.raw+json" \ + "repos/owner/repo/git/blobs/$blob" > "$work/files/$changed" + done + ``` + + The rest of the skill reads these files from `/files/`. Only the + changed files are stored. To read a caller or a definition elsewhere in the + repository, fetch that file the same way, with `git/trees/` to + find its blob sha. + +6. **Proceed to step 2** (gather surrounding context) using the stored files + instead of the working tree. + +The provenance line closes with `References link to this commit.`, because every +link is built against `headRefOid`. + Fetching a bare sha is not always allowed. The server decides whether to serve an object that no ref advertises. GitHub.com serves one that is reachable, and a GitHub Enterprise install may refuse. A base branch that was force-pushed or @@ -344,6 +450,14 @@ existing system. Ground every claim about what the code does in the code itself. Read the changed files at the target ref, and the callers and definitions they interact with. +**With a local clone**: read the changed files from the working tree after +fetching the PR ref into `refs/explain/pr-` (clone path) or a branch ref +(branch path). + +**Without a local clone**: the no-clone path stores each changed file's contents +at the head commit in `/files/`. Read from that location instead of +the working tree. + Ground the why in the durable record rather than in the diff alone. A diff shows what moved; it rarely says why that was the right move. Gather, in descending order of reliability: From b75a48b6162af20cfb2d4bd306d8da15e79665a6 Mon Sep 17 00:00:00 2001 From: Andy Horn Date: Tue, 3 Nov 2026 08:37:35 -0700 Subject: [PATCH 2/3] chore: drop the no-clone eval The eval harness isolates the environment, so the fixture cannot reach an authenticated gh and the case cannot pass. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01T58NPz2J74Vkr1ABminq2L --- evals/full/explain-pr-no-clone/case.yaml | 4 ---- evals/full/explain-pr-no-clone/fixture.sh | 6 ------ .../graders/no-shortened-paths.md | 6 ------ .../graders/no-template-placeholders.md | 6 ------ .../explain-pr-no-clone/graders/page-copied.md | 4 ---- .../graders/provenance-names-pr.md | 5 ----- .../graders/references-linked.md | 5 ----- .../explain-pr-no-clone/graders/skill-fired.md | 5 ----- evals/full/explain-pr-no-clone/prompt.md | 16 ---------------- 9 files changed, 57 deletions(-) delete mode 100644 evals/full/explain-pr-no-clone/case.yaml delete mode 100755 evals/full/explain-pr-no-clone/fixture.sh delete mode 100644 evals/full/explain-pr-no-clone/graders/no-shortened-paths.md delete mode 100644 evals/full/explain-pr-no-clone/graders/no-template-placeholders.md delete mode 100644 evals/full/explain-pr-no-clone/graders/page-copied.md delete mode 100644 evals/full/explain-pr-no-clone/graders/provenance-names-pr.md delete mode 100644 evals/full/explain-pr-no-clone/graders/references-linked.md delete mode 100644 evals/full/explain-pr-no-clone/graders/skill-fired.md delete mode 100644 evals/full/explain-pr-no-clone/prompt.md diff --git a/evals/full/explain-pr-no-clone/case.yaml b/evals/full/explain-pr-no-clone/case.yaml deleted file mode 100644 index 038857b..0000000 --- a/evals/full/explain-pr-no-clone/case.yaml +++ /dev/null @@ -1,4 +0,0 @@ -schema_version: "1.1" -name: explain-pr-no-clone -context: - scaffold_script: fixture.sh diff --git a/evals/full/explain-pr-no-clone/fixture.sh b/evals/full/explain-pr-no-clone/fixture.sh deleted file mode 100755 index 4a16ff6..0000000 --- a/evals/full/explain-pr-no-clone/fixture.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash -# The workspace stays empty and is not a git checkout, so the skill must take -# the no-clone path. It needs an authenticated gh to reach the repository. -set -e -gh auth status >/dev/null -! git rev-parse --git-dir >/dev/null 2>&1 diff --git a/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md b/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md deleted file mode 100644 index 21d3bb7..0000000 --- a/evals/full/explain-pr-no-clone/graders/no-shortened-paths.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -type: regex -target: { source: file, path: page.html } -pattern: '(class="filename"|)[^<]*\.\.\./' -match: not_contains ---- diff --git a/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md b/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md deleted file mode 100644 index c59d2e0..0000000 --- a/evals/full/explain-pr-no-clone/graders/no-template-placeholders.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -type: regex -target: { source: file, path: page.html } -pattern: 'FILL:' -match: not_contains ---- diff --git a/evals/full/explain-pr-no-clone/graders/page-copied.md b/evals/full/explain-pr-no-clone/graders/page-copied.md deleted file mode 100644 index ed36721..0000000 --- a/evals/full/explain-pr-no-clone/graders/page-copied.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -type: file_exists -path: page.html ---- diff --git a/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md b/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md deleted file mode 100644 index 59996d3..0000000 --- a/evals/full/explain-pr-no-clone/graders/provenance-names-pr.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -type: regex -target: { source: file, path: page.html } -pattern: 'class="provenance"[\s\S]{0,400}?PR 9' ---- diff --git a/evals/full/explain-pr-no-clone/graders/references-linked.md b/evals/full/explain-pr-no-clone/graders/references-linked.md deleted file mode 100644 index bad8f20..0000000 --- a/evals/full/explain-pr-no-clone/graders/references-linked.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -type: regex -target: { source: file, path: page.html } -pattern: 'References link to this commit\.' ---- diff --git a/evals/full/explain-pr-no-clone/graders/skill-fired.md b/evals/full/explain-pr-no-clone/graders/skill-fired.md deleted file mode 100644 index be7cc8c..0000000 --- a/evals/full/explain-pr-no-clone/graders/skill-fired.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -type: tool_used -tool: Skill -input_match: '"skill"\s*:\s*"(?:[\w-]+:)?explain-diff-html"' ---- diff --git a/evals/full/explain-pr-no-clone/prompt.md b/evals/full/explain-pr-no-clone/prompt.md deleted file mode 100644 index 1234ffd..0000000 --- a/evals/full/explain-pr-no-clone/prompt.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -tags: [full] -max_turns: 150 -timeout_seconds: 1800 -# allowed_tools only picks read-only tools. The run also needs Bash and Write, -# which only the CLI can grant: claude plugin eval . --allow-tools Write Bash -allowed_tools: [Read, Glob, Grep, Skill, Agent, TodoWrite] -runs: 1 -description: One end-to-end run against a real pull request from a workspace with no git checkout, graded on the produced page. ---- - -Explain https://github.com/malav2110/explain-diff-html/pull/9 as a -self-contained HTML page I can read to learn what changed and why. This -directory is not a clone of that repository. When the page is finished, also -copy it to `./page.html` in this directory so I can find it. If the home folder -is not writable here, write the page into this directory instead. From ffb7ba056e2284f7d2e9349145b30eb48993eaad Mon Sep 17 00:00:00 2001 From: Andy Horn Date: Tue, 17 Nov 2026 08:51:48 -0700 Subject: [PATCH 3/3] fix: address review feedback on no-clone PR support Read changed files with `git show :` on the clone path, since the fetch never checks the PR out. Name the no-clone file location in step 7, list the tree with `?recursive=1`, and report failed blob fetches instead of storing GitHub's error JSON. Move the clone overview to the top of step 1 and the no-clone path to its end, fix the `in_repo` detection block, add `commits` to the metadata fetch, and say the `git` requirement has an exception. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0137fL7B1JC5DHsTNFBAkNv7 --- README.md | 2 +- skills/explain-diff-html/SKILL.md | 244 ++++++++++-------- .../references/validation.md | 4 +- 3 files changed, 137 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index 696be21..e5d197a 100644 --- a/README.md +++ b/README.md @@ -188,7 +188,7 @@ tests the prose against the skill's writing rules. | Tool | Needed when | Used for | | ------ | ---------------------------------------- | -------------------------------------------------------------------------- | -| `git` | Reading from a local clone | Resolving the base, fetching the ref, reading the diff | +| `git` | Every run, except a PR with no clone | Resolving the base, fetching the ref, reading the diff | | `gh` | Explaining a pull request | Fetching the pull request data; with no clone, also the diff and files | | `node` | Every run, version 22.18 or later | Validating the page in step 7, and Mermaid sources in step 4 through `npx` | diff --git a/skills/explain-diff-html/SKILL.md b/skills/explain-diff-html/SKILL.md index f2f8dd0..ddc752a 100644 --- a/skills/explain-diff-html/SKILL.md +++ b/skills/explain-diff-html/SKILL.md @@ -39,14 +39,14 @@ Continue when the work still happens another way, and say what was weaker. | Tool | Needed when | Used for | | ------ | ---------------------------------------- | -------------------------------------------------------------------------- | -| `git` | Reading from a local clone | Resolving the base, fetching the ref, reading the diff | +| `git` | Every run, except a PR with no clone | Resolving the base, fetching the ref, reading the diff | | `gh` | Explaining a pull request | Fetching the pull request data; with no clone, also the diff and files | | `node` | Every run, version 22.18 or later | Validating the page in step 7, and Mermaid sources in step 4 through `npx` | Verify them up front: ```bash -command -v git >/dev/null || echo "git is required for local clones" +command -v git >/dev/null || echo "git is required, except for a PR with no clone" node -e 'const [major, minor] = process.versions.node.split(".").map(Number); process.exit(major > 22 || (major === 22 && minor >= 18) ? 0 : 1)' 2>/dev/null || echo "node 22.18 or later is required" @@ -112,44 +112,6 @@ be. A run whose change warrants none of those four shapes needs no Mermaid. The hand-built families cover it. Step 7 still needs Node to run the validator. -### Local clone vs. no clone - -The skill has two paths for explaining a pull request. - -**With a local clone** (the default path): the skill runs inside a git checkout, -uses `git fetch` and `gh pr view` to resolve the PR, and reads changed files -from the working tree. - -**Without a local clone**: the skill uses `gh pr view` with the `-R owner/repo` -flag to reach a repository you haven't cloned, and the GitHub API to -fetch file contents at the PR's head commit. This path requires `gh` to be -authenticated and a PR number or URL as the target. - -Both paths produce the same output format and honor the same output contract. -The only differences are how the skill resolves the target and gathers file -contents. - -Detect which path to use. A checkout only counts when it is the repository that -owns the pull request, so compare `origin` with the `owner/repo` parsed from the -target. Set `target_slug` to that value in lowercase, or leave it empty when the -target is a bare number, a branch, or a commit: - -```bash -in_repo=false -if command -v git >/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then - in_repo=true - origin_slug="$(git remote get-url origin 2>/dev/null | - sed -E 's#^(git@[^:]+:|[a-z+]+://[^/]+/)##; s#\.git$##' | tr '[:upper:]' '[:lower:]')" - if [ -n "$target_slug" ] && [ "$origin_slug" != "$target_slug" ]; then - in_repo=false - fi -fi -``` - -The rest of this step explains the clone path. The no-clone path follows the -same target-selection rules but replaces `git` and working-tree reads with `gh` -and the GitHub API. - ## Output contract - One self-contained HTML file. All CSS and JavaScript inline. Hand-built @@ -197,6 +159,52 @@ same rule. ### 1. Resolve the target and the filename key +#### Local clone vs. no clone + +The skill has two paths: one for any target in a local clone, and one for a pull +request only. + +**With a local clone** (the default path): the skill runs inside a git checkout, +uses `git fetch` and `gh pr view` to resolve the PR, and reads changed files +at the fetched ref with `git show :`. + +**Without a local clone**: the skill uses `gh pr view` with the `-R owner/repo` +flag to reach a repository you haven't cloned, and the GitHub API to +fetch file contents at the PR's head commit. This path requires `gh` to be +authenticated and a PR URL or `owner/repo#` as the target. A bare PR number +names no repository, so ask the user for it first. + +Both paths produce the same output format and honor the same output contract +for a pull request. The only differences are how the skill resolves the target +and gathers file contents. A branch, a commit range, or a single commit has no +recorded base without a clone, so the no-clone path refuses those. + +Detect which path to use. A checkout only counts when it is the repository that +owns the pull request, so compare `origin` with the `owner/repo` parsed from the +target. Set `target_slug` to that value in lowercase, or leave it empty when the +target is a bare number, a branch, or a commit: + +```bash +target_slug="" # empty for a bare number, a branch, or a commit +in_repo=false +if command -v git >/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then + in_repo=true + origin_slug="$(git remote get-url origin 2>/dev/null | + sed -E 's#^(git@[^:]+:|[a-z+]+://[^/]+/)##; s#\.git$##' | tr '[:upper:]' '[:lower:]')" + if [ -n "$target_slug" ] && [ "$origin_slug" != "$target_slug" ]; then + in_repo=false + fi +fi +echo "in_repo=$in_repo" +``` + +Each tool call starts a new shell, so set `target_slug` inside the block rather +than relying on an earlier call. + +The rest of this step explains the clone path, and the no-clone path closes the +step. The no-clone path replaces `git` and local reads with `gh` and the GitHub +API. + Determine what to explain, in this precedence: - An explicit pull request number or URL: @@ -301,72 +309,6 @@ works. The git form above still asks `gh` for the base commit, so it does not replace `gh`. Without `gh`, ask the user which commit the pull request is based on rather than guessing one. -#### No-clone path (for pull requests only, without a local git checkout) - -Use this path when `in_repo` is false and the target is a pull request. Without -a checkout, `gh` reaches the repository through `-R owner/repo` and the GitHub -API supplies the file contents. A branch, a commit range, or a single commit has -no recorded base to resolve without a clone, so for those stop and tell the user -to run from a checkout of the repository. - -1. **Parse the target** into `owner`, `repo`, and the number ``. From - `https://github.com/owner/repo/pull/123` or `owner/repo#123`, take all three. - From a bare number there is no repository to resolve, so ask the user for it. - -2. **Create the work directory** and write its path out for later steps, as the - clone path does: - - ```bash - work="$(mktemp -d)" - echo "$work" - ``` - -3. **Fetch the metadata** with the repository named: - - ```bash - gh pr view -R owner/repo --json title,body,url,headRefName,headRefOid,baseRefName - ``` - - `headRefOid` is the head commit. Resolve every `file:line` anchor against it, - use its short form in the provenance line, and keep the full 40 characters - for the links. Take the link host from the `url` returned here. - -4. **Fetch the diff** into the work directory, using the path from step 2: - - ```bash - gh pr diff -R owner/repo > /diff.txt - [ -s /diff.txt ] || echo "STOP: the diff is empty; resolve the base before drafting" - ``` - -5. **Store each changed file** as it stands at the head. List the files from the - paginated pull request files endpoint rather than from `gh pr view`, which - stops at 100. A file the pull request deleted has no head version, so the - filter skips it. Each file is read by blob sha, so no path needs URL-encoding, - and the raw media type returns the bytes without the 1 MB cap of the Contents - API. Do not name the loop variable `path`: in zsh it is tied to `PATH`. - - ```bash - work= - gh api "repos/owner/repo/pulls//files" --paginate \ - --jq '.[] | select(.status != "removed") | [.sha, .filename] | @tsv' | - while IFS=$'\t' read -r blob changed; do - mkdir -p "$work/files/$(dirname "$changed")" && - gh api -H "Accept: application/vnd.github.raw+json" \ - "repos/owner/repo/git/blobs/$blob" > "$work/files/$changed" - done - ``` - - The rest of the skill reads these files from `/files/`. Only the - changed files are stored. To read a caller or a definition elsewhere in the - repository, fetch that file the same way, with `git/trees/` to - find its blob sha. - -6. **Proceed to step 2** (gather surrounding context) using the stored files - instead of the working tree. - -The provenance line closes with `References link to this commit.`, because every -link is built against `headRefOid`. - Fetching a bare sha is not always allowed. The server decides whether to serve an object that no ref advertises. GitHub.com serves one that is reachable, and a GitHub Enterprise install may refuse. A base branch that was force-pushed or @@ -443,6 +385,81 @@ pattern accepts is the case that bites: key="$(printf '%s' "$key" | tr -c 'A-Za-z0-9-' '-' | tr -s '-')" ``` +#### No-clone path (for pull requests only, without a local git checkout) + +Use this path when `in_repo` is false and the target is a pull request. Without +a checkout, `gh` reaches the repository through `-R owner/repo` and the GitHub +API supplies the file contents. A branch, a commit range, or a single commit has +no recorded base to resolve without a clone, so for those stop and tell the user +to run from a checkout of the repository. + +1. **Parse the target** into `owner`, `repo`, and the number ``. From + `https://github.com/owner/repo/pull/123` or `owner/repo#123`, take all three. + From a bare number there is no repository to resolve, so ask the user for it. + +2. **Create the work directory** and write its path out for later steps, as the + clone path does: + + ```bash + work="$(mktemp -d)" + echo "$work" + ``` + +3. **Fetch the metadata** with the repository named: + + ```bash + gh pr view -R owner/repo --json title,body,url,headRefName,headRefOid,baseRefName,commits + ``` + + `headRefOid` is the head commit. Resolve every `file:line` anchor against it, + use its short form in the provenance line, and keep the full 40 characters + for the links. Take the link host from the `url` returned here. + +4. **Fetch the diff** into the work directory, using the path from step 2: + + ```bash + gh pr diff -R owner/repo > /diff.txt + [ -s /diff.txt ] || echo "STOP: gh pr diff returned nothing; report its error" + ``` + +5. **Store each changed file** as it stands at the head. List the files from the + paginated pull request files endpoint rather than from `gh pr view`, which + stops at 100. A file the pull request deleted has no head version, so the + filter skips it. Each file is read by blob sha, so no path needs URL-encoding, + and the raw media type returns the bytes without the 1 MB cap of the Contents + API. Do not name the loop variable `path`: in zsh it is tied to `PATH`. + + ```bash + work= + gh api "repos/owner/repo/pulls//files" --paginate \ + --jq '.[] | select(.status != "removed") | [.sha, .filename] | @tsv' | + while IFS=$'\t' read -r blob changed; do + mkdir -p "$work/files/$(dirname "$changed")" && + gh api -H "Accept: application/vnd.github.raw+json" \ + "repos/owner/repo/git/blobs/$blob" > "$work/files/$changed" || + { rm -f "$work/files/$changed"; echo "FAILED: $changed"; } + done + ``` + + A failed `gh api` still writes GitHub's error JSON to stdout, so the loop + removes the file and prints `FAILED: ` rather than leaving that JSON + stored as the file. A submodule bump always fails here: the files endpoint + lists the submodule path with a commit sha, and the blob fetch for it returns + 404. For a `FAILED` path, rely on the diff, which already shows the pointer + change. Report any other `FAILED` path rather than explaining it. + + The rest of the skill reads these files from `/files/`. Only the + changed files are stored. To read a caller or a definition elsewhere in the + repository, fetch that file the same way. List the tree with + `gh api "repos/owner/repo/git/trees/?recursive=1"` to find its + blob sha: without `recursive=1` the tree lists only the top level, so a file in + a subdirectory is missing. + +6. **Proceed to step 2** (gather surrounding context) using the stored files. + +The provenance line closes with `References link to this commit.`, because every +link is built against `headRefOid`. + ### 2. Gather surrounding context Explore the code the diff touches and the code around it, enough to explain the @@ -450,13 +467,14 @@ existing system. Ground every claim about what the code does in the code itself. Read the changed files at the target ref, and the callers and definitions they interact with. -**With a local clone**: read the changed files from the working tree after -fetching the PR ref into `refs/explain/pr-` (clone path) or a branch ref -(branch path). +**With a local clone**: read each changed file with `git show :`. +`` is `refs/explain/pr-` for a pull request, or the branch or commit that +was diffed. The fetch writes that ref and leaves the working tree alone, so the +working tree holds whatever the user has checked out, not necessarily the code +the diff describes. **Without a local clone**: the no-clone path stores each changed file's contents -at the head commit in `/files/`. Read from that location instead of -the working tree. +at the head commit in `/files/`. Read from that location. Ground the why in the durable record rather than in the diff alone. A diff shows what moved; it rarely says why that was the right move. Gather, in @@ -729,6 +747,10 @@ report, as step 2 says. A script runs the checks that are commands. You run the checks that need judgment. Read `references/validation.md`, in this skill's folder, before you start: it says what each check is and why it exists. +With no clone there is no local ref to re-read. The sub-agent works from its own +prompt, so put this in it: read a changed file from `/files/`, and +fetch any other file as step 1's no-clone path describes. + Run the script on the drafted page, with the short commit that the provenance line names. `` is the folder that holds this `SKILL.md`. Write each path and the commit out literally, as step 1 explains: diff --git a/skills/explain-diff-html/references/validation.md b/skills/explain-diff-html/references/validation.md index 1bf84d0..2a546aa 100644 --- a/skills/explain-diff-html/references/validation.md +++ b/skills/explain-diff-html/references/validation.md @@ -4,7 +4,9 @@ This is step 7 of the workflow in `SKILL.md`: what each check is, and why it exists. Start with the anchors, the code claims, and the links. Dispatch a read-only -sub-agent that re-reads each cited `path:line` at the target ref, checks that +sub-agent that re-reads each cited `path:line` at the target ref (with no clone, +a changed file is at `/files/` and any other file is fetched, as +step 1 of `SKILL.md` describes), checks that what the page says about that code still holds, and reports mismatches. Wait for that report, as step 2 of `SKILL.md` says, then fix every mismatch before saving. A wrong anchor and a wrong claim both survive every check below. The