docs: document script lib process helpers

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;
 

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<typeof setTimeout> | 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<typeof setTimeout> | null;

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",

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(

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 = /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)$/;
 const ALPHA_VERSION_REGEX =
   /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)-alpha\.(?<alpha>[1-9]\d*)$/;