docs: document script lib report helpers

scripts/lib/report-cli-helpers.mjs

@@ -1,6 +1,10 @@
+// Parses report CLI output arguments and writes optional artifacts.
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+/**
+ * Parses shared `--root`, `--json`, and `--markdown` flags for report scripts.
+ */
 export function parseReportCliArgs(argv) {
   const options = {
     rootDir: process.cwd(),
@@ -29,6 +33,9 @@ export function parseReportCliArgs(argv) {
   return options;
 }
 
+/**
+ * Writes an optional report artifact, creating its parent directory first.
+ */
 export async function writeReportArtifact(filePath, content) {
   if (!filePath) {
     return;

scripts/lib/run-extension-oxlint.mjs

@@ -1,3 +1,4 @@
+// Runs oxlint over extension source roots with repo-local boundary artifacts.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -8,6 +9,9 @@ import {
 } from "./local-heavy-check-runtime.mjs";
 import { createManagedCommandInvocation } from "./managed-child-process.mjs";
 
+/**
+ * Runs focused extension oxlint with a temp config and local heavy-check lock.
+ */
 export function runExtensionOxlint(params) {
   const repoRoot = process.cwd();
   const oxlintPath = path.resolve("node_modules", ".bin", "oxlint");

scripts/lib/source-file-scan-cache.mjs

@@ -1,3 +1,4 @@
+// Caches source file discovery and bounded-concurrency reads for guard scripts.
 import { promises as fs } from "node:fs";
 import path from "node:path";
 
@@ -42,6 +43,9 @@ function normalizeConcurrency(value) {
   return value;
 }
 
+/**
+ * Maps items with bounded worker concurrency while preserving input order.
+ */
 export async function mapWithConcurrency(items, concurrency, mapper) {
   const out = Array.from({ length: items.length });
   const workerCount = Math.min(normalizeConcurrency(concurrency), items.length);
@@ -62,6 +66,9 @@ export async function mapWithConcurrency(items, concurrency, mapper) {
   return out;
 }
 
+/**
+ * Collects sorted source files and cached contents for configured scan roots.
+ */
 export async function collectSourceFileContents(params) {
   const useCache = !params.readFile;
   const cacheKey = JSON.stringify({

scripts/lib/static-extension-assets.mjs

@@ -1,3 +1,4 @@
+// Discovers and copies static assets declared by bundled extension packages.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -96,6 +97,9 @@ function readPackageStaticAssetEntries(packageJson) {
   return Array.isArray(entries) ? entries : [];
 }
 
+/**
+ * Discovers static asset copy specs from extension package metadata.
+ */
 export function discoverStaticExtensionAssets(params = {}) {
   const rootDir = params.rootDir ?? process.cwd();
   const fsImpl = params.fs ?? fs;
@@ -151,6 +155,9 @@ function discoverStaticExtensionRuntimeOverlayAssets(params = {}) {
   return [...assetsByDest.values()].toSorted((left, right) => left.dest.localeCompare(right.dest));
 }
 
+/**
+ * Lists generated dist output paths for declared static extension assets.
+ */
 export function listStaticExtensionAssetOutputs(params = {}) {
   const assets = params.assets ?? discoverStaticExtensionAssets(params);
   return assets
@@ -158,6 +165,9 @@ export function listStaticExtensionAssetOutputs(params = {}) {
     .toSorted((left, right) => left.localeCompare(right));
 }
 
+/**
+ * Lists source file paths for declared static extension assets.
+ */
 export function listStaticExtensionAssetSources(params = {}) {
   const assets = params.assets ?? discoverStaticExtensionAssets(params);
   return assets
@@ -165,6 +175,9 @@ export function listStaticExtensionAssetSources(params = {}) {
     .toSorted((left, right) => left.localeCompare(right));
 }
 
+/**
+ * Copies declared static extension assets from source packages into root dist.
+ */
 export function copyStaticExtensionAssets(params = {}) {
   const rootDir = params.rootDir ?? process.cwd();
   const fsImpl = params.fs ?? fs;
@@ -182,6 +195,9 @@ export function copyStaticExtensionAssets(params = {}) {
   }
 }
 
+/**
+ * Copies static assets into the dist-runtime overlay from source or root dist.
+ */
 export function copyStaticExtensionAssetsToRuntimeOverlay(params = {}) {
   const rootDir = params.rootDir ?? process.cwd();
   const fsImpl = params.fs ?? fs;
@@ -209,6 +225,9 @@ export function copyStaticExtensionAssetsToRuntimeOverlay(params = {}) {
   }
 }
 
+/**
+ * Copies declared static assets for one package runtime build.
+ */
 export function copyStaticExtensionAssetsForPackage(params) {
   const rootDir = params.rootDir ?? process.cwd();
   const fsImpl = params.fs ?? fs;

scripts/lib/test-group-report.mjs

@@ -1,3 +1,4 @@
+// Builds grouped Vitest timing reports and comparisons for CI/test analysis.
 import path from "node:path";
 import {
   collectVitestAssertionDurations,
@@ -6,6 +7,9 @@ import {
 } from "../test-report-utils.mjs";
 import { formatMs } from "./vitest-report-cli-utils.mjs";
 
+/**
+ * Formats byte counts as megabytes, preserving missing RSS values as `n/a`.
+ */
 export function formatBytesAsMb(valueBytes) {
   return valueBytes === null || valueBytes === undefined
     ? "n/a"
@@ -22,10 +26,16 @@ function formatSignedBytesAsMb(valueBytes) {
     : `${valueBytes > 0 ? "+" : ""}${formatBytesAsMb(valueBytes)}`;
 }
 
+/**
+ * Shortens a Vitest config path into the label used by timing reports.
+ */
 export function normalizeConfigLabel(config) {
   return config.replace(/^test\/vitest\/vitest\./u, "").replace(/\.config\.ts$/u, "");
 }
 
+/**
+ * Derives a top-level test area from a repo-relative file path.
+ */
 export function resolveTestArea(file) {
   const normalized = normalizeTrackedRepoPath(file);
   const parts = normalized.split("/");
@@ -59,6 +69,9 @@ function resolveTestFolder(file, depth = 2) {
   return dir.split("/").slice(0, Math.max(1, depth)).join("/");
 }
 
+/**
+ * Derives the grouping key for area, folder, or top-level reports.
+ */
 export function resolveGroupKey(file, mode = "area") {
   if (mode === "folder") {
     return resolveTestFolder(file, 3);
@@ -96,6 +109,9 @@ function finalizeCounter(counter) {
   };
 }
 
+/**
+ * Aggregates Vitest report files into grouped timing counters and slow tests.
+ */
 export function buildGroupedTestReport(params) {
   const byGroup = new Map();
   const byConfig = new Map();
@@ -328,6 +344,9 @@ function compareRuns(beforeRuns = [], afterRuns = []) {
     });
 }
 
+/**
+ * Compares baseline and current grouped test reports.
+ */
 export function buildGroupedTestComparison(params) {
   const before = params.before;
   const after = params.after;
@@ -415,6 +434,9 @@ function pushFileChangeRows(lines, entries, options) {
   }
 }
 
+/**
+ * Renders a grouped test comparison as CLI-friendly text.
+ */
 export function renderGroupedTestComparison(comparison, options = {}) {
   const limit = options.limit ?? 25;
   const topFiles = options.topFiles ?? 25;
@@ -471,6 +493,9 @@ export function renderGroupedTestComparison(comparison, options = {}) {
   return lines.join("\n");
 }
 
+/**
+ * Renders a grouped test report as CLI-friendly text.
+ */
 export function renderGroupedTestReport(report, options = {}) {
   const limit = options.limit ?? 25;
   const topFiles = options.topFiles ?? 25;