Improve code organization and documentation

- Add comprehensive module documentation to index.ts
- Organize exports into clear sections with descriptive comments
- Add detailed fileoverview for purl-type.ts explaining all supported types
- Create shared logger utility for consistent script output
- Reduce cognitive complexity through better structure and clarity

Author: jdalton

scripts/utils/logger.mjs

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Shared logging utilities for scripts.
+ * Provides consistent console output formatting across all Socket scripts.
+ */
+
+import colors from 'yoctocolors-cjs'
+
+/**
+ * Console logger with colored status indicators
+ */
+export const log = {
+  info: msg => console.log(msg),
+  error: msg => console.error(`${colors.red('✗')} ${msg}`),
+  success: msg => console.log(`${colors.green('✓')} ${msg}`),
+  warn: msg => console.log(`${colors.yellow('⚠')} ${msg}`),
+  step: msg => console.log(`\n${msg}`),
+  substep: msg => console.log(`  ${msg}`),
+  progress: msg => process.stdout.write(`  ∴ ${msg}`),
+  done: msg => {
+    process.stdout.write('\r\x1b[K')
+    console.log(`  ${colors.green('✓')} ${msg}`)
+  },
+  failed: msg => {
+    process.stdout.write('\r\x1b[K')
+    console.log(`  ${colors.red('✗')} ${msg}`)
+  }
+}
+
+/**
+ * Print a section header with consistent formatting
+ */
+export function printHeader(title) {
+  console.log('\n' + '═'.repeat(60))
+  console.log(`  ${title}`)
+  console.log('═'.repeat(60))
+}
+
+/**
+ * Print a section footer with optional message
+ */
+export function printFooter(message) {
+  console.log('\n' + '═'.repeat(60))
+  if (message) {
+    console.log(`${colors.green('✓')} ${message}`)
+  }
+  console.log('═'.repeat(60))
+}

src/index.ts

@@ -22,33 +22,66 @@ SOFTWARE.
 
 /**
  * @fileoverview Main entry point for the socket-packageurl-js library.
- * Provides exports for PackageURL, PurlComponent, PurlQualifierNames, and PurlType.
+ *
+ * This library provides a complete implementation of the Package URL (purl) specification.
+ * Package URLs are used to identify and locate software packages in a standardized way
+ * across different package management systems and ecosystems.
+ *
+ * Core exports:
+ * - PackageURL: Main class for parsing and constructing package URLs
+ * - PackageURLBuilder: Builder pattern for constructing package URLs
+ * - PurlType: Type-specific normalization and validation rules
+ * - PurlComponent: Component encoding/decoding utilities
+ * - PurlQualifierNames: Known qualifier names from the specification
+ *
+ * Utility exports:
+ * - UrlConverter: Convert between purls and repository/download URLs
+ * - Result utilities: Functional error handling with Ok/Err pattern
  */
 
-/* c8 ignore start - Re-export only file, no logic to test. */
+/* c8 ignore start - Re-export only file, no logic to test */
+
+// ============================================================================
+// Core Classes and Functions
+// ============================================================================
 export {
-  Err,
-  Ok,
   PackageURL,
   PurlComponent,
   PurlQualifierNames,
   PurlType,
-  ResultUtils,
+} from './package-url.js'
+
+export { PackageURLBuilder } from './package-url-builder.js'
+
+// ============================================================================
+// Utility Classes and Functions
+// ============================================================================
+export {
   UrlConverter,
+} from './package-url.js'
+
+export {
+  Err,
+  Ok,
+  ResultUtils,
   err,
   ok,
 } from './package-url.js'
 
-// Import PackageURLBuilder separately to avoid circular dependency
-export { PackageURLBuilder } from './package-url-builder.js'
-
+// ============================================================================
+// TypeScript Type Definitions
+// ============================================================================
 export type {
   DownloadUrl,
   RepositoryUrl,
   Result,
 } from './package-url.js'
 
+// ============================================================================
+// Registry Integration
+// ============================================================================
 // Re-export PURL types from socket-registry for consistency
 export { PURL_Type } from '@socketsecurity/registry'
 export type { EcosystemString } from '@socketsecurity/registry'
+
 /* c8 ignore stop */

src/purl-type.ts

@@ -1,6 +1,15 @@
 /**
  * @fileoverview Package URL type-specific normalization and validation rules for different package ecosystems.
- * Implements PURL-TYPES specification rules for npm, pypi, maven, golang, and other package managers.
+ *
+ * This module implements the PURL-TYPES specification for various package managers:
+ * - NPM: Node.js packages with scoped namespace support
+ * - PyPI: Python packages with normalized naming
+ * - Maven: Java artifacts with group/artifact structure
+ * - Go: Go modules with module path validation
+ * - Cargo: Rust crates from crates.io
+ * - And 20+ other package types
+ *
+ * Each type has specific rules for namespace, name, version normalization and validation.
  */
 import { encodeComponent } from './encode.js'
 import { PurlError } from './error.js'