refactor(errors): tighten weak error messages to state the rule

Audit pass against the ERROR MESSAGES doctrine (what/where/saw/fix).
Four messages said "invalid" or "illegal" without naming the rule;
rewrite each to state the actual contract. Terse, library-API tier —
the four ingredients collapse into a single line per message.

- npm.ts: "Invalid scoped package specifier" → "npm scoped specifier
  must contain '/' after scope (e.g. '@scope/name')"
- vers.ts: "invalid semver version 'X'" → "semver version 'X' must
  match MAJOR.MINOR.PATCH (e.g. '1.2.3')"
- validate.ts qualifier: "qualifier 'X' contains an illegal
  character" → "qualifier key 'X' must match [a-z0-9.\-_]"
- validate.ts type: "type 'X' contains an illegal character" →
  "type 'X' must match [A-Za-z0-9.\-]"
- vers.ts: "empty constraint" → "VERS constraint must not be empty
  (use '*' for the wildcard)"

Test assertions updated to match the new messages. All 1775 tests
green. Other throws audited and left alone — they already state the
rule (e.g. "bazel requires a 'version' component", "cpan
'namespace' component must be UPPERCASE").

Author: jdalton

src/purl-types/npm.ts

@@ -390,7 +390,9 @@ export function parseNpmSpecifier(specifier: unknown): NpmPackageComponents {
     // Find the second slash (after @scope/)
     const slashIndex = StringPrototypeIndexOf(specifier, '/')
     if (slashIndex === -1) {
-      throw new Error('Invalid scoped package specifier.')
+      throw new Error(
+        'npm scoped specifier must contain "/" after scope (e.g. "@scope/name").',
+      )
     }
 
     // Find the @ after the scope

src/validate.ts

@@ -195,7 +195,7 @@ function validateQualifierKey(
       )
     ) {
       if (throws) {
-        throw new PurlError(`qualifier "${key}" contains an illegal character`)
+        throw new PurlError(`qualifier key "${key}" must match [a-z0-9.\\-_]`)
       }
       return false
     }
@@ -455,7 +455,7 @@ function validateType(
       )
     ) {
       if (throws) {
-        throw new PurlError(`type "${type}" contains an illegal character`)
+        throw new PurlError(`type "${type}" must match [A-Za-z0-9.\\-]`)
         /* v8 ignore next -- Unreachable code after throw. */
       }
       return false

src/vers.ts

@@ -94,7 +94,9 @@ const regexSemverNumberedGroups = ObjectFreeze(
 function parseSemver(version: string): SemverParts {
   const match = RegExpPrototypeExec(regexSemverNumberedGroups, version)
   if (!match) {
-    throw new PurlError(`invalid semver version "${version}"`)
+    throw new PurlError(
+      `semver version "${version}" must match MAJOR.MINOR.PATCH (e.g. "1.2.3")`,
+    )
   }
   const major = Number(match[1])
   const minor = Number(match[2])
@@ -225,7 +227,9 @@ function parseConstraint(raw: string): VersConstraint {
   }
   // Bare version implies equality
   if (trimmed.length === 0) {
-    throw new PurlError('empty constraint')
+    throw new PurlError(
+      'VERS constraint must not be empty (use "*" for the wildcard)',
+    )
   }
   return ObjectFreeze({
     __proto__: null,

test/package-url.test.mts

@@ -310,7 +310,7 @@ describe('PackageURL', () => {
               undefined,
               undefined,
             ),
-        ).toThrow(/contains an illegal character|cannot start with a number/)
+        ).toThrow(/must match \[A-Za-z0-9\.\\-\]|cannot start with a number/)
       },
     )
 
@@ -730,7 +730,7 @@ describe('PackageURL', () => {
 
     it('should reject invalid scoped package format', () => {
       expect(() => PackageURL.fromNpm('@babel')).toThrow(
-        'Invalid scoped package specifier',
+        'npm scoped specifier must contain "/" after scope',
       )
     })
   })
@@ -803,7 +803,7 @@ describe('PackageURL', () => {
       )
 
       expect(() => PackageURL.fromSpec('npm', '@babel')).toThrow(
-        'Invalid scoped package specifier',
+        'npm scoped specifier must contain "/" after scope',
       )
     })
 

test/parse-npm-specifier.test.mts

@@ -216,13 +216,13 @@ describe('parseNpmSpecifier', () => {
 
     it('should throw on invalid scoped package (missing slash)', () => {
       expect(() => parseNpmSpecifier('@babel')).toThrow(
-        'Invalid scoped package specifier.',
+        'npm scoped specifier must contain "/" after scope',
       )
     })
 
     it('should throw on invalid scoped package (only @ symbol)', () => {
       expect(() => parseNpmSpecifier('@')).toThrow(
-        'Invalid scoped package specifier.',
+        'npm scoped specifier must contain "/" after scope',
       )
     })
   })

test/purl-edge-cases.test.mts

@@ -909,7 +909,7 @@ describe('Edge cases and additional coverage', () => {
           validateQualifierKey(value as string, opts),
         'key',
         'key!invalid' as unknown,
-        /qualifier "key!invalid" contains an illegal character/,
+        /qualifier key "key!invalid" must match \[a-z0-9\.\\-_\]/,
         'validkey' as unknown,
       ],
       [
@@ -927,7 +927,7 @@ describe('Edge cases and additional coverage', () => {
           validateType(value, opts),
         'type',
         'type$illegal' as unknown,
-        /type "type\$illegal" contains an illegal character/,
+        /type "type\$illegal" must match \[A-Za-z0-9\.\\-\]/,
         'validtype' as unknown,
       ],
       [
@@ -1209,7 +1209,7 @@ describe('Edge cases and additional coverage', () => {
       // Test lines 73-76 - illegal character in key
       expect(() =>
         validateQualifierKey('key!invalid', { throws: true }),
-      ).toThrow(/qualifier "key!invalid" contains an illegal character/)
+      ).toThrow(/qualifier key "key!invalid" must match \[a-z0-9\.\\-_\]/)
 
       expect(validateQualifierKey('key!invalid', { throws: false })).toBe(false)
     })
@@ -1842,7 +1842,7 @@ describe('Edge cases and additional coverage', () => {
 
       // Test URL parsing failure (line 145 branch) - malformed URL
       expect(() => PackageURL.fromString('pkg::')).toThrow(
-        'type ":" contains an illegal character',
+        'type ":" must match [A-Za-z0-9.\\-]',
       )
 
       // Test the maybeUrlWithAuth branch where afterColon.length !== trimmedAfterColon.length