From 613a2835cbcd68f94ce462f88b6422819dc31f82 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 23:57:22 -0400 Subject: [PATCH] docs: document scoped script helpers --- scripts/github/dependency-guard.mjs | 3 +++ scripts/github/real-behavior-proof-check.mjs | 1 + scripts/github/real-behavior-proof-policy.mjs | 2 ++ scripts/mantis/build-telegram-desktop-proof-evidence.mjs | 4 ++++ scripts/mantis/build-telegram-evidence.mjs | 4 ++++ scripts/mantis/publish-pr-evidence.mjs | 4 ++++ scripts/perf/summarize-cpuprofile.mjs | 4 ++++ scripts/pre-commit/filter-staged-files.mjs | 1 + scripts/pre-commit/pnpm-audit-prod.mjs | 2 ++ scripts/repro/limit-edge-case-live-proof.mjs | 4 ++++ scripts/secrets/openclaw-bws-resolver.mjs | 1 + scripts/test-planner/vitest-args.mjs | 6 ++++++ 12 files changed, 36 insertions(+) diff --git a/scripts/github/dependency-guard.mjs b/scripts/github/dependency-guard.mjs index 588da5ce5f12..44aad78523d5 100644 --- a/scripts/github/dependency-guard.mjs +++ b/scripts/github/dependency-guard.mjs @@ -1,8 +1,11 @@ #!/usr/bin/env node +// GitHub dependency-change guard: detects dependency files, manages override +// comments/labels, and can autoscrub lockfile-only PR changes. import { appendFile, readFile } from "node:fs/promises"; import { readBoundedResponseText } from "../lib/bounded-response.mjs"; +/** Marker used to identify dependency guard comments. */ export const dependencyChangeMarker = ""; export const dependencyGraphGuardMarker = ""; export const dependencyChangedLabel = "dependencies-changed"; diff --git a/scripts/github/real-behavior-proof-check.mjs b/scripts/github/real-behavior-proof-check.mjs index 2329ec5005ad..d33ad52254f6 100644 --- a/scripts/github/real-behavior-proof-check.mjs +++ b/scripts/github/real-behavior-proof-check.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Checks PR real-behavior proof labels/comments and writes GitHub Action outputs. import { readFileSync } from "node:fs"; import { pathToFileURL } from "node:url"; import { diff --git a/scripts/github/real-behavior-proof-policy.mjs b/scripts/github/real-behavior-proof-policy.mjs index 95b713733e2d..91d49628a11a 100644 --- a/scripts/github/real-behavior-proof-policy.mjs +++ b/scripts/github/real-behavior-proof-policy.mjs @@ -1,5 +1,7 @@ +// Shared real-behavior proof policy for GitHub PR checks and label decisions. import { readBoundedResponseText } from "../lib/bounded-response.mjs"; +/** Label that lets maintainers override real-behavior proof requirements. */ export const PROOF_OVERRIDE_LABEL = "proof: override"; export const PROOF_SUPPLIED_LABEL = "proof: supplied"; export const PROOF_SUFFICIENT_LABEL = "proof: sufficient"; diff --git a/scripts/mantis/build-telegram-desktop-proof-evidence.mjs b/scripts/mantis/build-telegram-desktop-proof-evidence.mjs index e7e9333c3afc..7c7373bfbc17 100644 --- a/scripts/mantis/build-telegram-desktop-proof-evidence.mjs +++ b/scripts/mantis/build-telegram-desktop-proof-evidence.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Builds an HTML/manifest evidence bundle from Telegram Desktop proof artifacts. import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; @@ -159,6 +160,9 @@ function laneArtifactEntries() { ]); } +/** + * Builds the manifest for paired baseline/candidate Telegram Desktop proof artifacts. + */ export function buildTelegramDesktopProofManifest({ baseline, baselineRef, diff --git a/scripts/mantis/build-telegram-evidence.mjs b/scripts/mantis/build-telegram-evidence.mjs index b8b1144d2995..145ce2254219 100644 --- a/scripts/mantis/build-telegram-evidence.mjs +++ b/scripts/mantis/build-telegram-evidence.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Builds an HTML/manifest evidence bundle from Telegram QA scenario summaries. import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; @@ -88,6 +89,9 @@ function renderObservedMessages(observedMessages) { .join("\n"); } +/** + * Renders a self-contained Telegram evidence HTML report. + */ export function renderTelegramEvidenceHtml({ observedMessages, summary }) { const counts = summary.counts ?? {}; const pass = counts.failed === 0 && Number(counts.total ?? 0) > 0; diff --git a/scripts/mantis/publish-pr-evidence.mjs b/scripts/mantis/publish-pr-evidence.mjs index eccd4b12a2a3..89fcedea1d88 100644 --- a/scripts/mantis/publish-pr-evidence.mjs +++ b/scripts/mantis/publish-pr-evidence.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Publishes evidence manifest artifacts and optional PR comments for Mantis proof. import { execFileSync } from "node:child_process"; import { createHash, createHmac } from "node:crypto"; import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"; @@ -86,6 +87,9 @@ function resolveArtifact(manifestDir, artifact) { }; } +/** + * Loads and validates an evidence manifest from disk. + */ export function loadEvidenceManifest(manifestPath) { const resolvedManifest = path.resolve(manifestPath); const manifestDir = path.dirname(resolvedManifest); diff --git a/scripts/perf/summarize-cpuprofile.mjs b/scripts/perf/summarize-cpuprofile.mjs index 181a2c5d1df0..e070626cee5f 100644 --- a/scripts/perf/summarize-cpuprofile.mjs +++ b/scripts/perf/summarize-cpuprofile.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Summarizes V8 CPU profile files by frame and module. import fs from "node:fs"; import path from "node:path"; import process from "node:process"; @@ -7,6 +8,9 @@ import { parsePositiveInt } from "../lib/numeric-options.mjs"; const DEFAULT_LIMIT = 30; +/** + * Parses CPU profile file paths and --limit. + */ export function parseArgs(argv) { const files = []; let limit = DEFAULT_LIMIT; diff --git a/scripts/pre-commit/filter-staged-files.mjs b/scripts/pre-commit/filter-staged-files.mjs index 2206a0240ce9..02c4247b2a60 100644 --- a/scripts/pre-commit/filter-staged-files.mjs +++ b/scripts/pre-commit/filter-staged-files.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Filters staged file paths for pre-commit lint/format hooks. import path from "node:path"; /** diff --git a/scripts/pre-commit/pnpm-audit-prod.mjs b/scripts/pre-commit/pnpm-audit-prod.mjs index bbbd365d2533..850e8c1a9a20 100644 --- a/scripts/pre-commit/pnpm-audit-prod.mjs +++ b/scripts/pre-commit/pnpm-audit-prod.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node +// Production dependency audit helper using pnpm lock data and npm bulk advisories. import { readFile } from "node:fs/promises"; import path from "node:path"; import process from "node:process"; @@ -8,6 +9,7 @@ import { pathToFileURL } from "node:url"; const DEFAULT_REGISTRY = "https://registry.npmjs.org"; const BULK_ADVISORY_PATH = "/-/npm/v1/security/advisories/bulk"; const MIN_SEVERITY = "high"; +/** Maximum advisory error body characters retained in messages. */ export const BULK_ADVISORY_ERROR_BODY_MAX_CHARS = 4096; export const BULK_ADVISORY_RESPONSE_BODY_MAX_BYTES = 8 * 1024 * 1024; export const BULK_ADVISORY_REQUEST_TIMEOUT_MS = 60_000; diff --git a/scripts/repro/limit-edge-case-live-proof.mjs b/scripts/repro/limit-edge-case-live-proof.mjs index 1d2bda930f48..39e2c40eeae6 100644 --- a/scripts/repro/limit-edge-case-live-proof.mjs +++ b/scripts/repro/limit-edge-case-live-proof.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Live repro for numeric limit edge cases across diagnostics, usage, and voice-call CLI. import assert from "node:assert/strict"; /** * Live repro for limit/CLI numeric fixes (PR #82679). Run: pnpm exec tsx scripts/repro/limit-edge-case-live-proof.mjs @@ -15,6 +16,9 @@ import { resetDiagnosticPhasesForTest, } from "../../src/logging/diagnostic-phase.ts"; +/** + * Creates and cleans a temp root for live proof fixtures. + */ export async function withProofTempRoot(callback) { const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-proof-")); try { diff --git a/scripts/secrets/openclaw-bws-resolver.mjs b/scripts/secrets/openclaw-bws-resolver.mjs index 2381e57cb8aa..79b5571d18bd 100755 --- a/scripts/secrets/openclaw-bws-resolver.mjs +++ b/scripts/secrets/openclaw-bws-resolver.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Resolves SecretRef requests against Bitwarden Secrets Manager without printing secrets. import { execFileSync } from "node:child_process"; const readStdin = () => diff --git a/scripts/test-planner/vitest-args.mjs b/scripts/test-planner/vitest-args.mjs index ca385b77b59a..7f8278718dc6 100644 --- a/scripts/test-planner/vitest-args.mjs +++ b/scripts/test-planner/vitest-args.mjs @@ -1,3 +1,5 @@ +// Parses Vitest passthrough args for test-planner entry filter accounting. +/** Vitest options that consume the following CLI token as a value. */ export const OPTION_TAKES_VALUE = new Set([ "-t", "-c", @@ -37,8 +39,12 @@ export const OPTION_TAKES_VALUE = new Set([ "--experimental", ]); +/** Flags that only make sense for a single generated test run. */ export const SINGLE_RUN_ONLY_FLAGS = new Set(["--coverage", "--outputFile", "--mergeReports"]); +/** + * Splits Vitest passthrough args into file filters and option args. + */ export const parsePassthroughArgs = (args = []) => { const fileFilters = []; const optionArgs = [];