@vzn/vx-ci 0.0.642 → 0.0.643

package/README.md

@@ -55,16 +55,26 @@ github({
 
 ## Cache scope
 
-On Actions (`GITHUB_ACTIONS=true`), when `.vx/workspace.ts` sets no `cache.scope`, the plugin's
-`config` stage sets it from the ref (`GITHUB_REF`, `GITHUB_REF_NAME`, and
-the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch sets
-none (reads and writes the default keys), a pull request becomes
-`pr-<n>` (so is a `pull_request_target`, `issue_comment` or `workflow_run`
-run on a PR's behalf, by `GITHUB_EVENT_NAME`, though its ref is main's) and any other branch or tag `ref-<name>`, which read the
-default keys, then their own, and write only their own. A PR never writes what main
-reads. Whether a run writes at all is `cache.policy`'s call. `VX_CACHE_SCOPE` or a `cache.scope` in `.vx/workspace.ts` overrides it. This is a client-side convention: the real boundary is a cache
-token the server limits, so give PR jobs one that cannot write the
-default keys (`docs/security.md` § Cache poisoning).
+On Actions (`GITHUB_ACTIONS=true`) the plugin's `config` stage names the
+run's branch through `ctx.setBranch`, from the ref (`GITHUB_REF`,
+`GITHUB_REF_NAME`, `GITHUB_HEAD_REF`, `GITHUB_REPOSITORY`) and the
+`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope (reads and writes
+the default keys). A push to, or a pull request from, a branch names
+`<owner>/<repo>:<branch>` of the repository the branch lives in, so a
+fork's pull request names the fork; so does a `pull_request_target` or
+`workflow_run` run on a PR's behalf (by `GITHUB_EVENT_NAME`, though its
+ref is main's), and an `issue_comment` on a PR, which names no branch,
+`pr-<n>`. A pull request also names its base commit
+(`pull_request.base.sha`), so vx diffs the merge checkout from it with
+no git call. A scoped run's changed tasks read the scope's remote entry,
+the rest the default keys, and every task it builds is saved to the
+remote under the scope; the local cache never knows a scope. A
+PR never writes what main reads, and a laptop on the branch derives the
+same scope. Whether a run writes at all is `cache.policy`'s call.
+`VX_CACHE_SCOPE` overrides it. This is a client-side convention: the
+real boundary is a cache token the server limits, so give PR jobs one
+that cannot write the default keys (`docs/security.md` § Cache
+poisoning).
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.642",
+  "version": "0.0.643",
   "license": "MIT",
   "description": "GitHub Actions integration for vx — a telemetry plugin that writes the run as a GitHub Actions job summary.",
   "keywords": [
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.642"
+    "@vzn/vx": "^0.0.643"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -1,49 +1,92 @@
-// The cache scope a GitHub Actions run gets when the workspace names none:
-// the default branch writes the default keys, anything else its own scope.
+// The cache scope and base commit a GitHub Actions run names through
+// `setBranch`: the default branch writes the default keys, a branch its own
+// scope, the one a laptop on that branch reads (owner, 2026-10-17).
 import { readFile } from 'node:fs/promises'
+import { branchCacheScope } from '@vzn/vx'
 
 /**
- * `undefined` (the default keys) on a push to the
- * default branch, outside Actions, or when the ref is unknown; else
- * `pr-<n>` for a pull request and `ref-<name>` for any other branch or tag.
- * An event that runs in the default branch's context on a pull request's
- * behalf (`pull_request_target`, `issue_comment` on a PR, a `workflow_run`
- * a PR started) is the PR's, whatever `GITHUB_REF` says: a workflow that
- * checks out the PR's head there would otherwise write the default keys.
+ * What an Actions run knows of its branch (owner, 2026-10-17). `scope`:
+ * none on a push to the default branch, outside Actions, or when the ref
+ * is unknown; else `<owner>/<repo>:<branch>`, the repository and branch a
+ * pull request comes from, or the branch or tag pushed. A fork's pull
+ * request names the fork, a scope a laptop on the base repository never
+ * derives. An event that runs in the default branch's context on a pull
+ * request's behalf (`pull_request_target`, `issue_comment` on a PR, a
+ * `workflow_run` a PR started) is the PR's, whatever `GITHUB_REF` says: a
+ * workflow that checks out the PR's head there would otherwise write the
+ * default keys. `issue_comment` names no branch, so it writes `pr-<n>`.
+ * `base`: a pull request's base commit (`pull_request.base.sha`), what its
+ * merge checkout is compared with, no git call needed.
  */
-export async function githubCacheScope(
+export async function githubBranch(
   env: Readonly<Record<string, string | undefined>>,
-): Promise<string | undefined> {
-  if (env['GITHUB_ACTIONS'] !== 'true') return undefined
+): Promise<{ scope?: string; base?: string }> {
+  if (env['GITHUB_ACTIONS'] !== 'true') return {}
   const ref = env['GITHUB_REF'] ?? ''
-  const pr = /^refs\/pull\/(\d+)\//.exec(ref)
-  if (pr !== null) return `pr-${pr[1]}`
   const event = await eventOf(env['GITHUB_EVENT_PATH'])
-  const onBehalf = prOf(env['GITHUB_EVENT_NAME'], event)
-  if (onBehalf !== undefined) return onBehalf
+  const repo = stringOf(event?.repository?.full_name) ?? env['GITHUB_REPOSITORY']
+  const base = stringOf(event?.pull_request?.base?.sha)
+  const withBase = (scope: string | undefined): { scope?: string; base?: string } => ({
+    ...(scope !== undefined ? { scope } : {}),
+    ...(base !== undefined ? { base } : {}),
+  })
+  if (/^refs\/pull\/\d+\//.test(ref)) {
+    const head = event?.pull_request?.head
+    const branch = env['GITHUB_HEAD_REF'] || stringOf(head?.ref)
+    if (branch !== undefined)
+      return withBase(headScope(branch, stringOf(head?.repo?.full_name), repo))
+    return withBase('pr-target')
+  }
+  const onBehalf = prOf(env['GITHUB_EVENT_NAME'], event, repo)
+  if (onBehalf !== undefined) return withBase(onBehalf)
   const name = env['GITHUB_REF_NAME']
-  if (ref === '' || name === undefined || name === '') return undefined
+  if (ref === '' || name === undefined || name === '' || repo === undefined) return {}
   const branch = event?.repository?.default_branch
-  if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`)
-    return undefined
-  // `cache.scope` takes letters, digits and . _ - / @; a ref may hold more.
-  return `ref-${name.replace(/[^\w.@/-]/g, '_').slice(0, 124)}`
+  if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`) return {}
+  return { scope: branchCacheScope(repo, name) }
 }
 
 interface ActionsEvent {
-  repository?: { default_branch?: unknown }
-  pull_request?: { number?: unknown }
+  repository?: { default_branch?: unknown; full_name?: unknown }
+  pull_request?: {
+    number?: unknown
+    head?: { ref?: unknown; repo?: { full_name?: unknown } }
+    base?: { sha?: unknown }
+  }
   issue?: { number?: unknown; pull_request?: unknown }
-  workflow_run?: { event?: unknown; pull_requests?: { number?: unknown }[] }
+  workflow_run?: {
+    event?: unknown
+    head_branch?: unknown
+    head_repository?: { full_name?: unknown }
+    pull_requests?: { number?: unknown }[]
+  }
 }
 
-/** The PR scope of an event that runs in the base branch's context for a PR; `pr-target` when its number is unknown. */
-function prOf(name: string | undefined, event: ActionsEvent | undefined): string | undefined {
-  const scope = (n: unknown): string =>
-    typeof n === 'number' && Number.isInteger(n) && n > 0 ? `pr-${n}` : 'pr-target'
-  if (name === 'pull_request_target') return scope(event?.pull_request?.number)
+function stringOf(v: unknown): string | undefined {
+  return typeof v === 'string' && v !== '' ? v : undefined
+}
+
+/** A head branch's scope: the repository it lives in (a fork's own), then the branch. */
+function headScope(branch: string, headRepo: string | undefined, repo: string | undefined): string {
+  return branchCacheScope(headRepo ?? repo ?? 'unknown/unknown', branch)
+}
+
+/** The scope of an event that runs in the base branch's context for a PR; `pr-target` when its head is unknown. */
+function prOf(
+  name: string | undefined,
+  event: ActionsEvent | undefined,
+  repo: string | undefined,
+): string | undefined {
+  if (name === 'pull_request_target') {
+    const head = event?.pull_request?.head
+    const branch = stringOf(head?.ref)
+    return branch === undefined
+      ? 'pr-target'
+      : headScope(branch, stringOf(head?.repo?.full_name), repo)
+  }
   if (name === 'issue_comment' && event?.issue?.pull_request != null) {
-    return scope(event.issue.number)
+    const n = event.issue.number
+    return typeof n === 'number' && Number.isInteger(n) && n > 0 ? `pr-${n}` : 'pr-target'
   }
   const run = event?.workflow_run
   if (
@@ -51,7 +94,10 @@ function prOf(name: string | undefined, event: ActionsEvent | undefined): string
     typeof run?.event === 'string' &&
     run.event.startsWith('pull_request')
   ) {
-    return scope(run.pull_requests?.[0]?.number)
+    const branch = stringOf(run.head_branch)
+    return branch === undefined
+      ? 'pr-target'
+      : headScope(branch, stringOf(run.head_repository?.full_name), repo)
   }
   return undefined
 }

package/src/plugin.ts

@@ -13,7 +13,7 @@ import {
   type VxPlugin,
 } from '@vzn/vx'
 import type { FetchFn } from './checks.js'
-import { githubCacheScope } from './cache-scope.js'
+import { githubBranch } from './cache-scope.js'
 
 // Every run evaluates `.vx/workspace.ts`; the sink, the summary renderer
 // and the Checks API client load only where a summary file is set. The
@@ -40,9 +40,11 @@ export interface GithubPluginOptions {
   /** Check-run name. Default: `'vx'`. */
   checkName?: string
   /**
-   * Set the workspace's `cache.scope` from the run's ref when it names none:
-   * a push to the default branch keeps the default keys, a pull request writes to
-   * `pr-<n>`, any other ref to `ref-<name>`. Default: on; `false` opts out.
+   * Name the run's cache scope and base commit from the Actions event: a
+   * push to the default branch keeps the default keys, a branch or its pull
+   * request writes to `<owner>/<repo>:<branch>` (a fork's names the fork),
+   * and a pull request is compared with its base commit. `VX_CACHE_SCOPE`
+   * beats it. Default: on; `false` opts out.
    */
   cacheScope?: boolean
   /** Test seam — inject the append. Defaults to fs appendFile. */
@@ -94,10 +96,9 @@ export function github(options: GithubPluginOptions = {}): VxPlugin | undefined
       throw new UserError(`github() option "${key}" must be a non-empty string, got ""`)
   }
   return definePlugin(import.meta, {
-    async config(workspace) {
-      if (options.cacheScope === false || workspace.cache?.scope !== undefined) return
-      const scope = await githubCacheScope(process.env)
-      if (scope !== undefined) workspace.cache = { ...workspace.cache, scope }
+    async config(_workspace, ctx) {
+      if (options.cacheScope === false) return
+      ctx.setBranch(await githubBranch(process.env))
     },
     telemetry(ctx) {
       const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']