@vzn/vx-ci 0.0.650 → 0.0.652

package/README.md

@@ -25,7 +25,8 @@ That's the whole setup. On a GitHub Actions runner (`GITHUB_STEP_SUMMARY`
 set) every `vx run` appends a summary block, on its own line after
 anything already written in the step: verdict headline, stats
 (tasks / executed / cache hits / duration, and the ideal time an executor says
-the run could have taken, as `@vzn/vx-dte` replays it), failures called out above the
+the run could have taken, as `@vzn/vx-dte` replays it), the workers
+that would have run it best (`@vzn/vx-dte`'s "Workers to declare"), failures called out above the
 per-task table (rows by status, failures first, then the longest first) with their exit code, the signal an exit above 128
 stands for (`exit 137 (128 + SIGKILL)`, as the run's own frame and
 `vx last` say it), a timeout as `timed out, exit 143`, a persistent task
@@ -111,8 +112,12 @@ variables, as `github()` does on Actions. The default branch
 subgroup's project is `group/sub/app:feat-x`, the scope a laptop on
 `feat-x` derives. A merge request pipeline names its source branch
 (`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`) in the project it lives in (a
-fork's `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base
-(`CI_MERGE_REQUEST_DIFF_BASE_SHA`), the base of a bare `--affected`.
+fork's `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and the base of a bare
+`--affected`: its diff base (`CI_MERGE_REQUEST_DIFF_BASE_SHA`); in a
+merged results pipeline the target head it merged onto
+(`CI_MERGE_REQUEST_TARGET_BRANCH_SHA`), so changes the target took
+since are not run again; in a merge train the car ahead (`HEAD^1`),
+whose own pipeline runs its changes.
 A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
 builds what lands on the target, so it is trusted: no scope. As on
 Actions, the scope keys only plugin entries. A remote reads the tag, else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.650",
+  "version": "0.0.652",
   "license": "MIT",
   "description": "GitHub Actions and GitLab CI integration for vx — a job summary on Actions and the branch cache scope on both.",
   "keywords": [
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.650"
+    "@vzn/vx": "^0.0.652"
   },
   "repository": {
     "type": "git",

package/src/gitlab.ts

@@ -10,7 +10,8 @@ export interface GitlabPluginOptions {
    * Name the run's cache scope and base commit from GitLab's predefined
    * variables: none on the default branch or a merge train, else
    * `<project path>:<branch>`; a merge request is compared with its diff
-   * base. The scope keys plugin entries only. `VX_CACHE_SCOPE` beats it.
+   * base, a merged results pipeline with the target head, a train car
+   * with the car ahead. The scope keys plugin entries only. `VX_CACHE_SCOPE` beats it.
    * Default: on; `false` opts out.
    */
   cacheScope?: boolean
@@ -41,7 +42,7 @@ export function gitlab(options: GitlabPluginOptions = {}): VxPlugin | undefined
 /**
  * What a GitLab CI job knows of its branch. A merge request pipeline names
  * its source branch in the project it lives in (a fork's own,
- * `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base; a merge
+ * `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its base (`baseOf`); a merge
  * train's pipeline builds what lands on the target, so it is trusted; a
  * branch or tag pipeline names its ref, none on the default branch.
  * `refs`, what a remote reads (2026-10-25): a merge train's only its
@@ -80,8 +81,24 @@ function gitlabBranch(
   return refs.length === 0 ? facts : { ...facts, refs }
 }
 
+/**
+ * The commit a bare `--affected` compares with. A merged results pipeline
+ * runs the merge onto the target's head, so it is compared with that head:
+ * the diff base took in every change the target got since the branch
+ * forked. A train's car is merged onto the car ahead (its first parent,
+ * GitLab's `first_parent_ref`), whose pipeline runs that car's changes.
+ * Any other merge request pipeline runs its source branch: the diff base.
+ */
+function baseOf(value: (key: string) => string | undefined): string | undefined {
+  const event = value('CI_MERGE_REQUEST_EVENT_TYPE')
+  if (event === 'merge_train') return 'HEAD^1'
+  const diffBase = value('CI_MERGE_REQUEST_DIFF_BASE_SHA')
+  if (event === 'merged_result') return value('CI_MERGE_REQUEST_TARGET_BRANCH_SHA') ?? diffBase
+  return diffBase
+}
+
 function scopeOf(value: (key: string) => string | undefined): BranchFacts {
-  const base = value('CI_MERGE_REQUEST_DIFF_BASE_SHA')
+  const base = baseOf(value)
   const withBase = (facts: BranchFacts): BranchFacts =>
     base === undefined ? facts : { ...facts, base }
   if (value('CI_MERGE_REQUEST_EVENT_TYPE') === 'merge_train') return withBase({ trusted: true })

package/src/summary.ts

@@ -198,6 +198,9 @@ export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): s
   if (summary.machines !== undefined && summary.machines.length > 0) {
     lines.push(...renderWorkers(summary.machines, summary.tasks), '')
   }
+  if (summary.advice !== undefined && summary.advice.length > 0) {
+    lines.push(...renderAdvice(summary.advice), '')
+  }
 
   const header = ['Task', 'Status', 'Duration']
   lines.push(`| ${header.join(' | ')} |`)
@@ -237,6 +240,36 @@ const tasksCell = (ok: number, failed: number): string =>
 
 const pct = (x: number): string => `${Math.round(x * 100)}%`
 
+/** What each `WorkerAdvice` played. */
+const ADVICE = {
+  declared: 'The fewest of the declared sizes',
+  more: "Past the sizes' max",
+  any: 'Any cores, least core time',
+} as const
+
+/**
+ * The workers that would have run it best (2026-11-05: "So I can add more
+ * or change their specs"): played again from what each task took.
+ */
+function renderAdvice(advice: NonNullable<RunSummaryRecord['advice']>): string[] {
+  const lines = [
+    '### Workers to declare',
+    '',
+    '| Played on | Workers | Ends at |',
+    '| --- | --- | --- |',
+  ]
+  for (const a of advice)
+    lines.push(
+      `| ${ADVICE[a.of]} | ${a.workers
+        .map(
+          (w) =>
+            `${w.count} × ${w.size === undefined ? '' : `${escapeMarkdownCell(escapeInline(w.size))} `}(${w.cores} cores, ${gb(w.memoryBytes)} GB${w.platform === undefined ? '' : `, ${escapeMarkdownCell(escapeInline(w.platform))}`})`,
+        )
+        .join(' + ')} | ${fmtMs(a.endMs)} |`,
+    )
+  return lines
+}
+
 /**
  * The workers an executor ran the run on (vx-dte's): the cores its tasks
  * booked beside the cores they used, each averaged over the time the