From 44cd0ec13fbb0fb317961c1f30d5ca19c86ad845 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 23:03:25 -0400 Subject: [PATCH] docs: document script lib plugin helpers --- scripts/lib/pairing-guard-context.mjs | 2 ++ scripts/lib/plugin-contract-test-plan.mjs | 2 ++ scripts/lib/plugin-gateway-gauntlet.mjs | 1 + scripts/lib/plugin-npm-package-manifest.mjs | 9 ++++++++- scripts/lib/plugin-npm-runtime-assets.mjs | 3 +++ 5 files changed, 16 insertions(+), 1 deletion(-) diff --git a/scripts/lib/pairing-guard-context.mjs b/scripts/lib/pairing-guard-context.mjs index e34df00529c6..71baf24a04fc 100644 --- a/scripts/lib/pairing-guard-context.mjs +++ b/scripts/lib/pairing-guard-context.mjs @@ -1,6 +1,8 @@ +// Builds shared repo/source-root context for pairing guard scripts. import path from "node:path"; import { resolveRepoRoot, resolveSourceRoots } from "./ts-guard-utils.mjs"; +/** Create repo root and source root helpers for pairing guard scanners. */ export function createPairingGuardContext(importMetaUrl) { const repoRoot = resolveRepoRoot(importMetaUrl); const sourceRoots = resolveSourceRoots(repoRoot, ["src", "extensions"]); diff --git a/scripts/lib/plugin-contract-test-plan.mjs b/scripts/lib/plugin-contract-test-plan.mjs index 4e86fcfa38e5..55247240987f 100644 --- a/scripts/lib/plugin-contract-test-plan.mjs +++ b/scripts/lib/plugin-contract-test-plan.mjs @@ -1,3 +1,4 @@ +// Builds balanced Vitest shard plans for plugin contract tests. import { listTrackedTestFiles } from "./list-test-files.mjs"; function listContractTestFiles(rootDir = "src/plugins/contracts") { @@ -32,6 +33,7 @@ function resolveContractFileWeight(file) { return CONTRACT_FILE_WEIGHTS.get(name) ?? 10; } +/** Create balanced plugin contract test shards for CI check planning. */ export function createPluginContractTestShards() { const suffixes = ["a", "b"]; const groups = Object.fromEntries( diff --git a/scripts/lib/plugin-gateway-gauntlet.mjs b/scripts/lib/plugin-gateway-gauntlet.mjs index 2bf6cb415d69..b525ce999e43 100644 --- a/scripts/lib/plugin-gateway-gauntlet.mjs +++ b/scripts/lib/plugin-gateway-gauntlet.mjs @@ -1,3 +1,4 @@ +// Collects plugin manifest and metric observations for gateway gauntlet reports. import fs from "node:fs"; import path from "node:path"; import JSON5 from "json5"; diff --git a/scripts/lib/plugin-npm-package-manifest.mjs b/scripts/lib/plugin-npm-package-manifest.mjs index eba47a2cdc7a..f89e55f3b077 100644 --- a/scripts/lib/plugin-npm-package-manifest.mjs +++ b/scripts/lib/plugin-npm-package-manifest.mjs @@ -1,14 +1,15 @@ +// Augments plugin npm package manifests with generated runtime/package metadata. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import path from "node:path"; import { pathToFileURL } from "node:url"; import JSON5 from "json5"; import { packageJsonForShrinkwrap, readShrinkwrapOverrides } from "../generate-npm-shrinkwrap.mjs"; +import { resolveNpmRunner } from "../npm-runner.mjs"; import { listPluginNpmRuntimeBuildOutputs, resolvePluginNpmRuntimeBuildPlan, } from "./plugin-npm-runtime-build.mjs"; -import { resolveNpmRunner } from "../npm-runner.mjs"; const GENERATED_BUNDLED_CHANNEL_CONFIG_METADATA_PATH = "src/config/bundled-channel-config-metadata.generated.ts"; @@ -137,6 +138,7 @@ function listConfiguredBundledDependencyNames(packageJson) { return []; } +/** Resolve an npm command invocation for plugin package scripts. */ export function resolvePluginNpmCommand(args, params = {}) { return resolveNpmRunner({ comSpec: params.comSpec, @@ -405,6 +407,7 @@ function installPackageLocalBundledDependencies(params) { }; } +/** Build the package.json that should be used while packaging a plugin for npm. */ export function resolveAugmentedPluginNpmPackageJson(params) { const repoRoot = path.resolve(params.repoRoot ?? "."); const packageDir = resolvePackageDir(repoRoot, params.packageDir); @@ -462,6 +465,7 @@ export function resolveAugmentedPluginNpmPackageJson(params) { }; } +/** Read generated bundled channel config metadata keyed by plugin id. */ export function readGeneratedBundledChannelConfigs(repoRoot) { const metadataPath = path.join(repoRoot, GENERATED_BUNDLED_CHANNEL_CONFIG_METADATA_PATH); if (!fs.existsSync(metadataPath)) { @@ -528,6 +532,7 @@ function readGeneratedBundledChannelConfigEntries(source) { } } +/** Merge generated channel config schemas into a plugin manifest without clobbering labels. */ export function mergeGeneratedChannelConfigs(manifest, generatedChannelConfigs) { if (!generatedChannelConfigs || Object.keys(generatedChannelConfigs).length === 0) { return manifest; @@ -561,6 +566,7 @@ export function mergeGeneratedChannelConfigs(manifest, generatedChannelConfigs) }; } +/** Build the plugin manifest that should be used while packaging a plugin for npm. */ export function resolveAugmentedPluginNpmManifest(params) { const repoRoot = path.resolve(params.repoRoot ?? "."); const packageDir = resolvePackageDir(repoRoot, params.packageDir); @@ -590,6 +596,7 @@ export function resolveAugmentedPluginNpmManifest(params) { }; } +/** Temporarily write augmented manifest/package metadata while a packaging callback runs. */ export function withAugmentedPluginNpmManifestForPackage(params, callback) { const repoRoot = path.resolve(params.repoRoot ?? "."); const packageDir = resolvePackageDir(repoRoot, params.packageDir); diff --git a/scripts/lib/plugin-npm-runtime-assets.mjs b/scripts/lib/plugin-npm-runtime-assets.mjs index 62c3f4dd7e5a..7cf3f1e69820 100644 --- a/scripts/lib/plugin-npm-runtime-assets.mjs +++ b/scripts/lib/plugin-npm-runtime-assets.mjs @@ -1,3 +1,4 @@ +// Builds and validates static assets needed by package-local plugin runtime output. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import path from "node:path"; @@ -8,6 +9,7 @@ function resolvePackageAssetBuildCommand(packageJson) { return typeof command === "string" && command.trim() ? command.trim() : null; } +/** Run a package-local static asset build command when the plugin declares one. */ export function runPackageAssetBuild(plan) { const command = resolvePackageAssetBuildCommand(plan.packageJson); if (!command) { @@ -26,6 +28,7 @@ export function runPackageAssetBuild(plan) { return command; } +/** List static asset source paths referenced by a package but missing from disk. */ export function listMissingPackageStaticAssetSources(plan) { const packagePrefix = `extensions/${plan.pluginDir}/`; return discoverStaticExtensionAssets({ rootDir: plan.repoRoot })