Add module and method documentation headers to scripts

Author: jdalton

scripts/check-registry-package-types.mjs

@@ -1,3 +1,5 @@
+/** @fileoverview Validate that all registry package constants have corresponding TypeScript type declarations. */
+
 import { createRequire } from 'node:module'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
@@ -8,6 +10,10 @@ import constants from './constants.mjs'
 
 const require = createRequire(import.meta.url)
 
+/**
+ * Verify that all constants have matching TypeScript declarations.
+ * @throws {Error} When a constant is missing from type declarations.
+ */
 async function main() {
   const { registryPkgPath, rootPath } = constants
 

scripts/clean-test-cache.mjs

@@ -1,8 +1,13 @@
+/** @fileoverview Clean test cache directories for npm package tests. */
+
 import os from 'node:os'
 import path from 'node:path'
 
 import { safeRemove } from './utils/fs.mjs'
 
+/**
+ * Remove all test cache directories.
+ */
 async function cleanTestCache() {
   const dirs = [
     path.join(os.homedir(), '.socket-npm-test-cache'),

scripts/convert-requires-to-imports.mjs

@@ -1,13 +1,13 @@
-/**
- * Convert CommonJS require() calls to dynamic import() for constants.
- * This allows Vite to properly resolve and transform them during coverage.
- */
+/** @fileoverview Convert CommonJS require() calls to dynamic import() for constants. */
 
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 const libDir = './registry/src/lib'
 
+/**
+ * Convert require calls to dynamic imports in a file.
+ */
 function processFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   let modified = false
@@ -38,6 +38,9 @@ function processFile(filePath) {
   return 0
 }
 
+/**
+ * Recursively process all TypeScript files in a directory.
+ */
 function processDirectory(dir) {
   let count = 0
   const files = readdirSync(dir, { withFileTypes: true })

scripts/fix-import-extensions.mjs

@@ -1,8 +1,13 @@
+/** @fileoverview Add .js extensions to relative import statements. */
+
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 const libDir = './registry/src/lib'
 
+/**
+ * Add .js extensions to imports missing them.
+ */
 function processFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   let modified = false
@@ -44,6 +49,9 @@ function processFile(filePath) {
   return 0
 }
 
+/**
+ * Recursively process all TypeScript files in a directory.
+ */
 function processDirectory(dir) {
   let count = 0
   const files = readdirSync(dir, { withFileTypes: true })

scripts/generate-actions-allow-list.mjs

@@ -1,3 +1,5 @@
+/** @fileoverview Generate GitHub Actions allow list from workflow and action dependencies. */
+
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
@@ -8,6 +10,9 @@ const GITHUB_PATH = '.github'
 const WORKFLOWS_PATH = path.join(GITHUB_PATH, 'workflows')
 const ACTIONS_PATH = path.join(GITHUB_PATH, 'actions')
 
+/**
+ * Extract action dependencies from a workflow or action file.
+ */
 async function extractDependencies(filePath) {
   const content = await fs.readFile(filePath, 'utf8')
   const dependencies = new Set()
@@ -44,6 +49,9 @@ async function extractDependencies(filePath) {
   return dependencies
 }
 
+/**
+ * Recursively find all YAML files in a directory.
+ */
 async function getAllYamlFiles(dir) {
   const files = []
   try {
@@ -62,6 +70,9 @@ async function getAllYamlFiles(dir) {
   return files
 }
 
+/**
+ * Generate and display GitHub Actions allow list.
+ */
 async function main() {
   const allDependencies = new Set()
 

scripts/rebuild-registry-exports.mjs

@@ -1,3 +1,5 @@
+/** @fileoverview Rebuild package.json exports field from built dist files. */
+
 import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -10,6 +12,9 @@ const __dirname = path.dirname(__filename)
 const registryPath = path.join(__dirname, '..', 'registry')
 const packageJsonPath = path.join(registryPath, 'package.json')
 
+/**
+ * Generate package.json exports from dist directory structure.
+ */
 async function main() {
   const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'))
 

scripts/release-npm-packages.mjs

@@ -1,3 +1,5 @@
+/** @fileoverview Detect package changes and bump versions for npm release. */
+
 import crypto from 'node:crypto'
 import fs from 'node:fs/promises'
 import path from 'node:path'
@@ -40,6 +42,9 @@ const registryPkg = packageData({
 
 const EXTRACT_PACKAGE_TMP_PREFIX = 'release-npm-'
 
+/**
+ * Compute SHA256 hashes for all files in a local package directory.
+ */
 async function getLocalPackageFileHashes(packagePath) {
   const fileHashes = {}
 
@@ -125,6 +130,9 @@ async function getLocalPackageFileHashes(packagePath) {
   return toSortedObject(fileHashes)
 }
 
+/**
+ * Compute SHA256 hashes for all files in a remote published package.
+ */
 async function getRemotePackageFileHashes(spec) {
   const fileHashes = {}
 
@@ -187,6 +195,9 @@ async function getRemotePackageFileHashes(spec) {
   return toSortedObject(fileHashes)
 }
 
+/**
+ * Compare local and remote package files to detect changes.
+ */
 async function hasPackageChanged(pkg, manifest_, options) {
   const { state } = { __proto__: null, ...options }
 
@@ -231,12 +242,18 @@ async function hasPackageChanged(pkg, manifest_, options) {
   return changed
 }
 
+/**
+ * Check if a file is automatically included by npm in published packages.
+ */
 function isNpmAutoIncluded(fileName) {
   const upperName = fileName.toUpperCase()
   // NPM automatically includes LICENSE and README files with any case and extension.
   return upperName.startsWith('LICENSE') || upperName.startsWith('README')
 }
 
+/**
+ * Bump package version if changes are detected.
+ */
 async function maybeBumpPackage(pkg, options) {
   const {
     spinner,
@@ -284,6 +301,9 @@ async function maybeBumpPackage(pkg, options) {
   }
 }
 
+/**
+ * Create package metadata with defaults.
+ */
 function packageData(data) {
   const { manifest, printName = data.name, tag = LATEST, version } = data
   return Object.assign(data, {
@@ -294,6 +314,9 @@ function packageData(data) {
   })
 }
 
+/**
+ * Detect changes and bump versions for all packages.
+ */
 async function main() {
   const { spinner } = constants
 

scripts/remove-require-js-extensions.mjs

@@ -1,8 +1,13 @@
+/** @fileoverview Remove .js extensions from require() calls with relative paths. */
+
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 const libDir = './registry/src/lib'
 
+/**
+ * Remove .js extensions from require calls in a file.
+ */
 function processFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   let modified = false
@@ -27,6 +32,9 @@ function processFile(filePath) {
   return 0
 }
 
+/**
+ * Recursively process all TypeScript files in a directory.
+ */
 function processDirectory(dir) {
   let count = 0
   const files = readdirSync(dir, { withFileTypes: true })

scripts/revert-import-extensions.mjs

@@ -1,8 +1,13 @@
+/** @fileoverview Revert import extensions by removing .js extensions from relative imports. */
+
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 const libDir = './registry/src/lib'
 
+/**
+ * Remove .js extensions from import statements in a file.
+ */
 function processFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   let modified = false
@@ -28,6 +33,9 @@ function processFile(filePath) {
   return 0
 }
 
+/**
+ * Recursively process all TypeScript files in a directory.
+ */
 function processDirectory(dir) {
   let count = 0
   const files = readdirSync(dir, { withFileTypes: true })

scripts/set-npm-package-access.mjs

@@ -1,3 +1,5 @@
+/** @fileoverview Set MFA automation access level for published npm packages. */
+
 import path from 'node:path'
 
 import { parseArgs } from '../registry/dist/lib/parse-args.js'
@@ -25,11 +27,17 @@ const { values: cliArgs } = parseArgs({
   strict: false,
 })
 
+/**
+ * Create package metadata with defaults.
+ */
 function packageData(data) {
   const { printName = data.name } = data
   return Object.assign(data, { printName })
 }
 
+/**
+ * Configure MFA automation for token-based packages.
+ */
 async function main() {
   // Exit early if not running in CI or with --force.
   const { ENV } = constants