refactor: add full TypeScript types to core script files

Author: jdalton

scripts/clean.mts

@@ -23,12 +23,21 @@ const rootPath = path.resolve(
 /**
  * Clean specific directories.
  */
-async function cleanDirectories(tasks, options = {}) {
+interface CleanTask {
+  name: string
+  pattern?: string
+  patterns?: string[]
+}
+
+async function cleanDirectories(
+  tasks: CleanTask[],
+  options: { quiet?: boolean } = {},
+): Promise<number> {
   const { quiet = false } = options
 
   for (const task of tasks) {
     const { name, pattern, patterns } = task
-    const patternsToDelete = patterns || [pattern]
+    const patternsToDelete = patterns ?? (pattern ? [pattern] : [])
 
     if (!quiet) {
       logger.progress(`Cleaning ${name}`)

scripts/constants/paths.mts

@@ -12,14 +12,14 @@ import process from 'node:process'
 /**
  * Normalize path separators for cross-platform compatibility.
  */
-function normalizePath(p) {
+function normalizePath(p: string): string {
   return p.split(path.sep).join(path.posix.sep)
 }
 
 /**
  * Find project root by looking for pnpm-workspace.yaml.
  */
-function findProjectRoot() {
+function findProjectRoot(): string {
   let currentPath = process.cwd()
   const root = path.parse(currentPath).root
 

scripts/constants/utils.mts

@@ -20,44 +20,44 @@ import {
 /**
  * Get cached default which command options with augmented PATH.
  */
-let _defaultWhichOptions
-export function getDefaultWhichOptions() {
+let _defaultWhichOptions: { path: string } | undefined
+export function getDefaultWhichOptions(): { path: string } {
   if (_defaultWhichOptions === undefined) {
     _defaultWhichOptions = {
       __proto__: null,
-      path: `${ROOT_NODE_MODULES_BIN_PATH}${path.delimiter}${process.env.PATH}`,
-    }
+      path: `${ROOT_NODE_MODULES_BIN_PATH}${path.delimiter}${process.env['PATH']}`,
+    } as { path: string }
   }
-  return _defaultWhichOptions
+  return _defaultWhichOptions!
 }
 
 /**
  * Get root LICENSE file content.
  */
-let _licenseContent
-export function getLicenseContent() {
+let _licenseContent: string | undefined
+export function getLicenseContent(): string {
   if (_licenseContent === undefined) {
     _licenseContent = fs.readFileSync(ROOT_LICENSE_PATH, 'utf8')
   }
-  return _licenseContent
+  return _licenseContent!
 }
 
 /**
  * Get git executable path.
  */
-let _gitExecPath
-export function getGitExecPath() {
+let _gitExecPath: string | undefined
+export function getGitExecPath(): string {
   if (_gitExecPath === undefined) {
     _gitExecPath = which.sync('git', getDefaultWhichOptions())
   }
-  return _gitExecPath
+  return _gitExecPath!
 }
 
 /**
  * Get tsx executable path.
  */
-let _tsxExecPath
-export function getTsxExecPath() {
+let _tsxExecPath: string | undefined
+export function getTsxExecPath(): string {
   if (_tsxExecPath === undefined) {
     const tsxPath = path.join(ROOT_NODE_MODULES_BIN_PATH, 'tsx')
     if (fs.existsSync(tsxPath)) {
@@ -66,14 +66,14 @@ export function getTsxExecPath() {
       _tsxExecPath = which.sync('tsx', getDefaultWhichOptions())
     }
   }
-  return _tsxExecPath
+  return _tsxExecPath!
 }
 
 /**
  * Parse gitignore file and return ignore patterns.
  */
-let _gitIgnorePatterns
-export function getGitIgnorePatterns() {
+let _gitIgnorePatterns: string[] | undefined
+export function getGitIgnorePatterns(): string[] {
   if (_gitIgnorePatterns === undefined) {
     const gitignorePath = path.join(ROOT_PATH, '.gitignore')
     const content = fs.readFileSync(gitignorePath, 'utf8')
@@ -82,14 +82,14 @@ export function getGitIgnorePatterns() {
       .map(line => line.trim())
       .filter(line => line && !line.startsWith('#'))
   }
-  return _gitIgnorePatterns
+  return _gitIgnorePatterns!
 }
 
 /**
  * Get merged ignore globs from gitignore and standard exclusions.
  */
-let _ignoreGlobs
-export function getIgnoreGlobs() {
+let _ignoreGlobs: readonly string[] | undefined
+export function getIgnoreGlobs(): readonly string[] {
   if (_ignoreGlobs === undefined) {
     _ignoreGlobs = Object.freeze([
       ...new Set([
@@ -107,7 +107,7 @@ export function getIgnoreGlobs() {
       ]),
     ])
   }
-  return _ignoreGlobs
+  return _ignoreGlobs!
 }
 
 /**

scripts/fix.mts

@@ -17,7 +17,16 @@ import { spawn } from '@socketsecurity/lib/spawn'
 const WIN32 = process.platform === 'win32'
 const logger = getDefaultLogger()
 
-async function run(cmd, args, { label, required = true } = {}) {
+interface RunOptions {
+  label?: string
+  required?: boolean
+}
+
+async function run(
+  cmd: string,
+  args: string[],
+  { label, required = true }: RunOptions = {},
+): Promise<number> {
   try {
     const result = await spawn(cmd, args, {
       shell: WIN32,

scripts/lint.mts

@@ -41,7 +41,7 @@ const CONFIG_PATTERNS = [
 /**
  * Get oxfmt exclude patterns from .oxfmtrc.json.
  */
-function getOxfmtExcludePatterns() {
+function getOxfmtExcludePatterns(): string[] {
   try {
     const oxfmtConfigPath = path.join(process.cwd(), '.oxfmtrc.json')
     if (!existsSync(oxfmtConfigPath)) {
@@ -59,7 +59,7 @@ function getOxfmtExcludePatterns() {
 /**
  * Check if a file matches any of the exclude patterns.
  */
-function isExcludedByOxfmt(file, excludePatterns) {
+function isExcludedByOxfmt(file: string, excludePatterns: string[]): boolean {
   for (const pattern of excludePatterns) {
     // Convert glob pattern to regex-like matching.
     // Support **/ for directory wildcards and * for filename wildcards.
@@ -82,7 +82,10 @@ function isExcludedByOxfmt(file, excludePatterns) {
 /**
  * Check if we should run all linters based on changed files.
  */
-function shouldRunAllLinters(changedFiles) {
+function shouldRunAllLinters(changedFiles: string[]): {
+  runAll: boolean
+  reason?: string
+} {
   for (const file of changedFiles) {
     // Core library files
     if (CORE_FILES.has(file)) {
@@ -103,7 +106,7 @@ function shouldRunAllLinters(changedFiles) {
 /**
  * Filter files to only those that should be linted.
  */
-function filterLintableFiles(files) {
+function filterLintableFiles(files: string[]): string[] {
   // Only include extensions actually supported by oxfmt/oxlint
   const lintableExtensions = new Set([
     '.js',
@@ -139,18 +142,27 @@ function filterLintableFiles(files) {
  * @param {{ stderr?: string }} result
  * @returns {boolean}
  */
-function isOxfmtNoFilesResult(result) {
+function isOxfmtNoFilesResult(result: { stderr?: string }): boolean {
   const { stderr } = result
   return (
-    stderr?.includes('Expected at least one target file') ||
-    stderr?.includes('No files were processed in the specified paths')
+    (stderr?.includes('Expected at least one target file') ||
+      stderr?.includes('No files were processed in the specified paths')) ??
+    false
   )
 }
 
 /**
  * Run linters on specific files.
  */
-async function runLintOnFiles(files, options = {}) {
+interface LintOptions {
+  fix?: boolean
+  quiet?: boolean
+}
+
+async function runLintOnFiles(
+  files: string[],
+  options: LintOptions = {},
+): Promise<number> {
   const { fix = false, quiet = false } = options
 
   if (!files.length) {
@@ -217,7 +229,7 @@ async function runLintOnFiles(files, options = {}) {
 /**
  * Run linters on all files.
  */
-async function runLintOnAll(options = {}) {
+async function runLintOnAll(options: LintOptions = {}): Promise<number> {
   const { fix = false, quiet = false } = options
 
   if (!quiet) {
@@ -272,7 +284,21 @@ async function runLintOnAll(options = {}) {
 /**
  * Get files to lint based on options.
  */
-async function getFilesToLint(options) {
+interface GetFilesToLintOptions {
+  all?: boolean
+  changed?: boolean
+  staged?: boolean
+}
+
+interface FilesToLintResult {
+  files: string[] | 'all' | undefined
+  reason?: string
+  mode: string
+}
+
+async function getFilesToLint(
+  options: GetFilesToLintOptions,
+): Promise<FilesToLintResult> {
   const { all, changed, staged } = options
 
   // If --all, return early
@@ -308,7 +334,7 @@ async function getFilesToLint(options) {
 
   // Check if we should run all based on changed files
   const { reason, runAll } = shouldRunAllLinters(changedFiles)
-  if (runAll) {
+  if (runAll && reason) {
     return { files: 'all', reason, mode: 'all' }
   }
 
@@ -318,7 +344,7 @@ async function getFilesToLint(options) {
     return { files: undefined, reason: 'no lintable files changed', mode }
   }
 
-  return { files: lintableFiles, reason: undefined, mode }
+  return { files: lintableFiles, mode }
 }
 
 async function main(): Promise<void> {
@@ -381,6 +407,7 @@ async function main(): Promise<void> {
     }
 
     const quiet = isQuiet(values)
+    const fix = Boolean(values['fix'])
 
     if (!quiet) {
       printHeader('Lint Runner')
@@ -396,7 +423,7 @@ async function main(): Promise<void> {
         logger.step('Linting specified files')
       }
       exitCode = await runLintOnFiles(files, {
-        fix: values.fix,
+        fix,
         quiet,
       })
     } else {
@@ -414,7 +441,7 @@ async function main(): Promise<void> {
           logger.step(`Linting all files (${reason})`)
         }
         exitCode = await runLintOnAll({
-          fix: values.fix,
+          fix,
           quiet,
         })
       } else {
@@ -423,7 +450,7 @@ async function main(): Promise<void> {
           logger.step(`Linting ${modeText} files`)
         }
         exitCode = await runLintOnFiles(files, {
-          fix: values.fix,
+          fix,
           quiet,
         })
       }

scripts/publish.mts

@@ -7,6 +7,8 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import type { SpawnOptions } from '@socketsecurity/lib/spawn'
+
 import { parseArgs } from '@socketsecurity/lib/argv/parse'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
 import { spawn } from '@socketsecurity/lib/spawn'
@@ -21,7 +23,11 @@ const WIN32 = process.platform === 'win32'
 /**
  * Run a command with spawn.
  */
-async function runCommand(command, args = [], options = {}) {
+async function runCommand(
+  command: string,
+  args: string[] = [],
+  options: SpawnOptions = {},
+): Promise<number> {
   const result = await spawn(command, args, {
     stdio: 'inherit',
     cwd: rootPath,
@@ -34,7 +40,7 @@ async function runCommand(command, args = [], options = {}) {
 /**
  * Validate that build artifacts exist.
  */
-async function validateBuildArtifacts() {
+async function validateBuildArtifacts(): Promise<boolean> {
   logger.step('Validating build artifacts')
 
   // Check for registry package dist directory
@@ -59,7 +65,15 @@ async function validateBuildArtifacts() {
  * Publish packages using the complex multi-package flow.
  * Delegates to scripts/npm/publish-npm-packages.mjs.
  */
-async function publishComplex(options = {}) {
+interface PublishOptions {
+  force?: boolean
+  forcePublish?: boolean
+  forceRegistry?: boolean
+  skipNpmPackages?: boolean
+  tag?: string
+}
+
+async function publishComplex(options: PublishOptions = {}): Promise<boolean> {
   const {
     force = false,
     forcePublish = false,
@@ -194,13 +208,23 @@ async function main(): Promise<void> {
     }
 
     // Publish using complex flow (delegates to package-npm-publish script)
-    const publishSuccess = await publishComplex({
-      force: values.force,
-      forcePublish: values['force-publish'],
-      forceRegistry: values['force-registry'],
-      skipNpmPackages: values['skip-npm-packages'],
-      tag: values.tag,
-    })
+    const publishOpts: PublishOptions = {}
+    if (values['force']) {
+      publishOpts.force = true
+    }
+    if (values['force-publish']) {
+      publishOpts.forcePublish = true
+    }
+    if (values['force-registry']) {
+      publishOpts.forceRegistry = true
+    }
+    if (values['skip-npm-packages']) {
+      publishOpts.skipNpmPackages = true
+    }
+    if (values['tag']) {
+      publishOpts.tag = values['tag'] as string
+    }
+    const publishSuccess = await publishComplex(publishOpts)
 
     if (!publishSuccess && !values.force) {
       logger.error('Publish failed')