From 1da49dcfd02fa211da28d3f904760cd34f7133b8 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 22:59:33 -0400 Subject: [PATCH] docs: document script lib process helpers --- scripts/lib/local-heavy-check-runtime.mjs | 8 ++++++++ scripts/lib/managed-child-process.mjs | 9 +++++++++ scripts/lib/merge-head-diff-base.mjs | 2 ++ scripts/lib/mintlify-accordion.mjs | 4 ++++ scripts/lib/npm-publish-plan.mjs | 1 + 5 files changed, 24 insertions(+) diff --git a/scripts/lib/local-heavy-check-runtime.mjs b/scripts/lib/local-heavy-check-runtime.mjs index 2ec38ca69583..7a1d1a60d1ac 100644 --- a/scripts/lib/local-heavy-check-runtime.mjs +++ b/scripts/lib/local-heavy-check-runtime.mjs @@ -1,3 +1,4 @@ +// Applies local resource policy and process locks for expensive check commands. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import os from "node:os"; @@ -15,6 +16,7 @@ const DEFAULT_FAST_LOCAL_CHECK_MIN_MEMORY_BYTES = 48 * GIB; const DEFAULT_FAST_LOCAL_CHECK_MIN_CPUS = 12; const SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4)); +/** Return whether local-heavy-check safeguards are enabled for an environment. */ export function isLocalCheckEnabled(env) { const raw = env.OPENCLAW_LOCAL_CHECK?.trim().toLowerCase(); return raw !== "0" && raw !== "false"; @@ -24,6 +26,7 @@ function isCiLikeEnv(env = process.env) { return env.CI === "true" || env.GITHUB_ACTIONS === "true"; } +/** Ensure local check runs opt into safeguard environment outside CI. */ export function resolveLocalHeavyCheckEnv(env = process.env) { if (isCiLikeEnv(env) || isLocalCheckEnabled(env)) { return env; @@ -39,6 +42,7 @@ function hasFlag(args, name) { return args.some((arg) => arg === name || arg.startsWith(`${name}=`)); } +/** Apply local tsgo defaults for declaration skipping, caching, throttling, and profiling. */ export function applyLocalTsgoPolicy(args, env, hostResources) { const nextEnv = { ...env }; const nextArgs = [...args]; @@ -79,6 +83,7 @@ export function applyLocalTsgoPolicy(args, env, hostResources) { return { env: nextEnv, args: nextArgs }; } +/** Apply local oxlint defaults for type-aware checking and throttled worker settings. */ export function applyLocalOxlintPolicy(args, env, hostResources) { const nextEnv = { ...env }; const nextArgs = [...args]; @@ -107,6 +112,7 @@ export function applyLocalOxlintPolicy(args, env, hostResources) { return { env: nextEnv, args: nextArgs }; } +/** Decide whether an oxlint invocation needs the local heavy-check lock. */ export function shouldAcquireLocalHeavyCheckLockForOxlint( args, { cwd = process.cwd(), env = process.env } = {}, @@ -152,6 +158,7 @@ export function shouldAcquireLocalHeavyCheckLockForOxlint( }); } +/** Decide whether a tsgo invocation needs the local heavy-check lock. */ export function shouldAcquireLocalHeavyCheckLockForTsgo(args, env = process.env) { if (env.OPENCLAW_TSGO_FORCE_LOCK === "1") { return true; @@ -188,6 +195,7 @@ function shouldThrottleLocalHeavyChecks(env, hostResources, defaultMode = "throt ); } +/** Acquire a filesystem lock for one local heavy check and return its release callback. */ export function acquireLocalHeavyCheckLockSync(params) { const env = params.env ?? process.env; diff --git a/scripts/lib/managed-child-process.mjs b/scripts/lib/managed-child-process.mjs index 43ea4b71ec8f..3dfb2b8c616f 100644 --- a/scripts/lib/managed-child-process.mjs +++ b/scripts/lib/managed-child-process.mjs @@ -1,3 +1,4 @@ +// Runs child commands with process-group signal forwarding and Windows shell normalization. import { spawn } from "node:child_process"; import { constants as osConstants } from "node:os"; import { buildCmdExeCommandLine } from "../windows-cmd-helpers.mjs"; @@ -8,6 +9,8 @@ const managedChildren = new Set(); const signalHandlers = new Map(); /** + * Return conventional shell exit code for a signal. + * * @param {NodeJS.Signals} signal * @returns {number} */ @@ -45,6 +48,8 @@ function terminateManagedChild(child, signal = "SIGTERM") { } /** + * Run a child command while forwarding termination signals to the managed process group. + * * @param {{ * bin: string; * args?: string[]; @@ -113,6 +118,8 @@ export async function runManagedCommand({ } /** + * Build the spawn command, args, and options used by managed command execution. + * * @param {{ * child: import("node:child_process").ChildProcess; * forceKillTimer: ReturnType | null; @@ -125,6 +132,8 @@ function addManagedChild(managedChild) { } /** + * Build a normalized command invocation, including cmd.exe wrapping on Windows. + * * @param {{ * child: import("node:child_process").ChildProcess; * forceKillTimer: ReturnType | null; diff --git a/scripts/lib/merge-head-diff-base.mjs b/scripts/lib/merge-head-diff-base.mjs index 5b7c0e3f9aab..66a7aa60ba73 100644 --- a/scripts/lib/merge-head-diff-base.mjs +++ b/scripts/lib/merge-head-diff-base.mjs @@ -1,8 +1,10 @@ +// Resolves the diff base for merge commits when first-parent comparison is requested. import { execFileSync } from "node:child_process"; import { pathToFileURL } from "node:url"; const DEFAULT_GIT_OUTPUT_MAX_BUFFER = 16 * 1024 * 1024; +/** Resolve the git base ref to use when diffing a merge head. */ export function resolveMergeHeadDiffBase({ base, head = "HEAD", diff --git a/scripts/lib/mintlify-accordion.mjs b/scripts/lib/mintlify-accordion.mjs index 6dfbda120dfb..89d33bae9ced 100644 --- a/scripts/lib/mintlify-accordion.mjs +++ b/scripts/lib/mintlify-accordion.mjs @@ -1,3 +1,5 @@ +// Checks and repairs Mintlify component indentation that can swallow following markdown. +/** Lint message emitted for Mintlify component closing tags with unsafe indentation. */ export const MINTLIFY_ACCORDION_INDENT_MESSAGE = "Mintlify component closing tag is indented deeper than its opening tag; Mintlify can parse following markdown as nested content."; @@ -54,6 +56,7 @@ function visitMintlifyComponentIndentation(raw, onMisindentedClose, onMisindente return lines; } +/** Return indentation errors for Mintlify accordion-like components. */ export function checkMintlifyAccordionIndentation(raw) { const errors = []; visitMintlifyComponentIndentation(raw, ({ closeComponent, index }) => { @@ -66,6 +69,7 @@ export function checkMintlifyAccordionIndentation(raw) { return errors; } +/** Repair Mintlify component indentation and list-adjacent closing tags when needed. */ export function repairMintlifyAccordionIndentation(raw) { let changed = false; const lines = visitMintlifyComponentIndentation( diff --git a/scripts/lib/npm-publish-plan.mjs b/scripts/lib/npm-publish-plan.mjs index 9fa24e0d7509..02a605022ce0 100644 --- a/scripts/lib/npm-publish-plan.mjs +++ b/scripts/lib/npm-publish-plan.mjs @@ -1,3 +1,4 @@ +// Parses OpenClaw date-based release versions and npm dist-tag publish plans. const STABLE_VERSION_REGEX = /^(?\d{4})\.(?[1-9]\d?)\.(?[1-9]\d?)$/; const ALPHA_VERSION_REGEX = /^(?\d{4})\.(?[1-9]\d?)\.(?[1-9]\d?)-alpha\.(?[1-9]\d*)$/;