Resolve circular dependency and add length validation

- Move PackageURLBuilder export to index.ts to break circular dependency
- Add length validation for name (214), namespace (512), and version (256)

Author: jdalton

src/index.ts

@@ -30,7 +30,6 @@ export {
   Err,
   Ok,
   PackageURL,
-  PackageURLBuilder,
   PurlComponent,
   PurlQualifierNames,
   PurlType,
@@ -39,6 +38,10 @@ export {
   err,
   ok,
 } from './package-url.js'
+
+// Import PackageURLBuilder separately to avoid circular dependency.
+export { PackageURLBuilder } from './package-url-builder.js'
+
 export type {
   DownloadUrl,
   RepositoryUrl,

src/validate.ts

@@ -45,9 +45,28 @@ function validateName(
 ): boolean {
   // Support both legacy boolean parameter and new options object for backward compatibility.
   const opts = typeof options === 'boolean' ? { throws: options } : options
-  return (
-    validateRequired('name', name, opts) && validateStrings('name', name, opts)
-  )
+  const { throws = false } = opts ?? {}
+
+  // First validate it's a required string.
+  if (
+    !validateRequired('name', name, opts) ||
+    !validateStrings('name', name, opts)
+  ) {
+    return false
+  }
+
+  // Validate length (npm package name limit is 214 characters).
+  const MAX_NAME_LENGTH = 214
+  if (typeof name === 'string' && name.length > MAX_NAME_LENGTH) {
+    if (throws) {
+      throw new PurlError(
+        `"name" exceeds maximum length of ${MAX_NAME_LENGTH} characters`,
+      )
+    }
+    return false
+  }
+
+  return true
 }
 
 /**
@@ -60,7 +79,27 @@ function validateNamespace(
 ): boolean {
   // Support both legacy boolean parameter and new options object for backward compatibility.
   const opts = typeof options === 'boolean' ? { throws: options } : options
-  return validateStrings('namespace', namespace, opts)
+  const { throws = false } = opts ?? {}
+
+  if (!validateStrings('namespace', namespace, opts)) {
+    return false
+  }
+
+  // Validate length (reasonable limit for namespace).
+  const MAX_NAMESPACE_LENGTH = 512
+  if (
+    typeof namespace === 'string' &&
+    namespace.length > MAX_NAMESPACE_LENGTH
+  ) {
+    if (throws) {
+      throw new PurlError(
+        `"namespace" exceeds maximum length of ${MAX_NAMESPACE_LENGTH} characters`,
+      )
+    }
+    return false
+  }
+
+  return true
 }
 
 /**
@@ -311,7 +350,24 @@ function validateVersion(
 ): boolean {
   // Support both legacy boolean parameter and new options object for backward compatibility.
   const opts = typeof options === 'boolean' ? { throws: options } : options
-  return validateStrings('version', version, opts)
+  const { throws = false } = opts ?? {}
+
+  if (!validateStrings('version', version, opts)) {
+    return false
+  }
+
+  // Validate length (reasonable limit for version strings).
+  const MAX_VERSION_LENGTH = 256
+  if (typeof version === 'string' && version.length > MAX_VERSION_LENGTH) {
+    if (throws) {
+      throw new PurlError(
+        `"version" exceeds maximum length of ${MAX_VERSION_LENGTH} characters`,
+      )
+    }
+    return false
+  }
+
+  return true
 }
 
 export {