@vzn/vx-ci 0.0.524 → 0.0.526

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.524",
+  "version": "0.0.526",
   "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.524"
+    "@vzn/vx": "^0.0.526"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -10,6 +10,7 @@
 // Anywhere else the plugin declines and costs nothing.
 export { github, type GithubPluginOptions } from './plugin.js'
 export { renderJobSummary } from './summary.js'
+
 // The Checks API helpers are the plugin's own; only the transport type
 // the options name is public (1.0 freezes what this file exports).
 export { type FetchFn } from './checks.js'

package/src/plugin.ts

@@ -4,23 +4,15 @@
 // and no cost — so declaring `github()` is safe in every environment, the
 // same decline pattern as `otel()`.
 import { appendFile, stat } from 'node:fs/promises'
-import {
-  refuseUnknownOptions,
-  type PluginOptionKinds,
-  definePlugin,
-  type RunSummaryRecord,
-  type TelemetrySink,
-  type VxPlugin,
-} from '@vzn/vx'
-import {
-  buildCheckRunPayload,
-  postCheckRun,
-  resolveCheckRunEnv,
-  type CheckRunEnv,
-  type FetchFn,
-} from './checks.js'
+import { createRequire } from 'node:module'
+import { refuseUnknownOptions, type PluginOptionKinds, definePlugin, type VxPlugin } from '@vzn/vx'
+import type { FetchFn } from './checks.js'
 import { githubCacheScope } from './cache-scope.js'
-import { clampJobSummary, MAX_JOB_SUMMARY_BYTES, renderJobSummary } from './summary.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
+// telemetry hook is synchronous, so the module loads by `require`.
+const loadSink = (): typeof import('./sink.js') => createRequire(import.meta.url)('./sink.js')
 
 export interface GithubPluginOptions {
   /**
@@ -58,75 +50,6 @@ export interface GithubPluginOptions {
   sizeOf?: (file: string) => Promise<number>
 }
 
-export class GithubSummarySink implements TelemetrySink {
-  readonly name = 'github-job-summary'
-  /** Summary-only: no streaming records at all — zero per-event cost. */
-  readonly wants: [] = []
-  private summary: RunSummaryRecord | undefined
-
-  constructor(
-    private readonly file: string,
-    private readonly title: string,
-    private readonly append: (file: string, markdown: string) => Promise<void>,
-    private readonly warn: (m: string) => void,
-    private readonly check?: { env: CheckRunEnv; name: string; fetchFn: FetchFn },
-    /** Bytes the summary file already holds. */
-    private readonly sizeOf: (file: string) => Promise<number> = async () => 0,
-  ) {}
-
-  onRunSummary(summary: RunSummaryRecord): void {
-    // MUST return promptly (contract): stash, render + write in flush().
-    this.summary = summary
-  }
-
-  async flush(signal?: AbortSignal): Promise<void> {
-    if (this.summary === undefined) return
-    const markdown = renderJobSummary(this.summary, this.title)
-    // The two artifacts are INDEPENDENT, and the plugin already says so in
-    // one direction: it declines the check-run without a token and still
-    // writes the summary. The reverse has to hold, or a full disk on the
-    // runner costs the PR its check — the more visible of the two. Reported,
-    // not thrown: a telemetry sink may never break a run.
-    try {
-      // Clamped: past GitHub's 1 MiB cap the runner drops the summary whole,
-      // so a bounded page beats none. The cap covers the step's whole file,
-      // and a page clamped to 1 MiB after another writer's output lost both
-      // (F-42): the room is what is left. The check-run payload has its own,
-      // smaller cap and is clamped where it is built.
-      const used = await this.sizeOf(this.file)
-      // After another writer the page starts on its own line: one that left
-      // no final newline ran vx's heading into its paragraph (F-51).
-      const lead = used > 0 ? '\n' : ''
-      const page = clampJobSummary(markdown, MAX_JOB_SUMMARY_BYTES - used - lead.length)
-      if (page === '') {
-        this.warn(
-          `vx-ci: ${this.file} already holds ${used} bytes of GitHub's 1 MiB job summary cap — no room for vx's page`,
-        )
-      } else {
-        await this.append(this.file, lead + page)
-      }
-    } catch (err) {
-      this.warn(
-        `vx-ci: could not write the job summary to ${this.file}: ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-    if (this.check !== undefined) {
-      await postCheckRun({
-        env: this.check.env,
-        payload: buildCheckRunPayload({
-          summary: this.summary,
-          markdown,
-          name: this.check.name,
-          sha: this.check.env.sha,
-        }),
-        fetchFn: this.check.fetchFn,
-        warn: this.warn,
-        ...(signal === undefined ? {} : { signal }),
-      })
-    }
-  }
-}
-
 /**
  * Why a string cannot be an HTTP header value, or null. Bun's `fetch`
  * refuses a line break, a NUL or a character past Latin-1 once it has
@@ -166,6 +89,7 @@ export function github(options: GithubPluginOptions = {}): VxPlugin {
       const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']
       if (file === undefined || file === '') return undefined
       const append = options.append ?? (async (f: string, md: string) => appendFile(f, md, 'utf8'))
+      const { GithubSummarySink, resolveCheckRunEnv } = loadSink()
       let check: ConstructorParameters<typeof GithubSummarySink>[4]
       if (options.checks !== false) {
         const env = resolveCheckRunEnv(process.env)

package/src/sink.ts

@@ -0,0 +1,76 @@
+// The job summary sink: loaded only on a runner that sets a summary file,
+// so a run elsewhere pays no module of it.
+import { type RunSummaryRecord, type TelemetrySink } from '@vzn/vx'
+import { buildCheckRunPayload, postCheckRun, type CheckRunEnv, type FetchFn } from './checks.js'
+import { clampJobSummary, MAX_JOB_SUMMARY_BYTES, renderJobSummary } from './summary.js'
+
+export { resolveCheckRunEnv } from './checks.js'
+
+export class GithubSummarySink implements TelemetrySink {
+  readonly name = 'github-job-summary'
+  /** Summary-only: no streaming records at all — zero per-event cost. */
+  readonly wants: [] = []
+  private summary: RunSummaryRecord | undefined
+
+  constructor(
+    private readonly file: string,
+    private readonly title: string,
+    private readonly append: (file: string, markdown: string) => Promise<void>,
+    private readonly warn: (m: string) => void,
+    private readonly check?: { env: CheckRunEnv; name: string; fetchFn: FetchFn },
+    /** Bytes the summary file already holds. */
+    private readonly sizeOf: (file: string) => Promise<number> = async () => 0,
+  ) {}
+
+  onRunSummary(summary: RunSummaryRecord): void {
+    // MUST return promptly (contract): stash, render + write in flush().
+    this.summary = summary
+  }
+
+  async flush(signal?: AbortSignal): Promise<void> {
+    if (this.summary === undefined) return
+    const markdown = renderJobSummary(this.summary, this.title)
+    // The two artifacts are INDEPENDENT, and the plugin already says so in
+    // one direction: it declines the check-run without a token and still
+    // writes the summary. The reverse has to hold, or a full disk on the
+    // runner costs the PR its check — the more visible of the two. Reported,
+    // not thrown: a telemetry sink may never break a run.
+    try {
+      // Clamped: past GitHub's 1 MiB cap the runner drops the summary whole,
+      // so a bounded page beats none. The cap covers the step's whole file,
+      // and a page clamped to 1 MiB after another writer's output lost both
+      // (F-42): the room is what is left. The check-run payload has its own,
+      // smaller cap and is clamped where it is built.
+      const used = await this.sizeOf(this.file)
+      // After another writer the page starts on its own line: one that left
+      // no final newline ran vx's heading into its paragraph (F-51).
+      const lead = used > 0 ? '\n' : ''
+      const page = clampJobSummary(markdown, MAX_JOB_SUMMARY_BYTES - used - lead.length)
+      if (page === '') {
+        this.warn(
+          `vx-ci: ${this.file} already holds ${used} bytes of GitHub's 1 MiB job summary cap — no room for vx's page`,
+        )
+      } else {
+        await this.append(this.file, lead + page)
+      }
+    } catch (err) {
+      this.warn(
+        `vx-ci: could not write the job summary to ${this.file}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+    if (this.check !== undefined) {
+      await postCheckRun({
+        env: this.check.env,
+        payload: buildCheckRunPayload({
+          summary: this.summary,
+          markdown,
+          name: this.check.name,
+          sha: this.check.env.sha,
+        }),
+        fetchFn: this.check.fetchFn,
+        warn: this.warn,
+        ...(signal === undefined ? {} : { signal }),
+      })
+    }
+  }
+}