chore(tests): optimize test suite and improve documentation

- Create test/utils/assertions.mts with reusable helpers
- Consolidate duplicate test patterns (length validation, encoding)
- Extract global-mocking test to isolated config for safe concurrency
- Add vitest config documentation for standard vs isolated tests
- Update CLAUDE.md with test naming conventions
- Improve docs with visual aids and critical-info-first structure

Reduces test duplication by ~900 lines, maintains 100% coverage, and
enables safe concurrent execution for 99.75% of tests (867/868).

Author: jdalton

.config/vitest.config.isolated.mts

@@ -1,6 +1,25 @@
 /**
- * @fileoverview Vitest configuration for tests requiring full isolation.
- * Used for tests that need vi.doMock() or other module-level mocking.
+ * @fileoverview Vitest configuration for tests requiring full process isolation.
+ *
+ * USE THIS CONFIG FOR:
+ * - Tests that modify global objects (global.URL, global.process, etc.)
+ * - Tests using vi.doMock() for dynamic module mocking
+ * - Tests that would cause race conditions in concurrent execution
+ * - Tests requiring complete process-level isolation
+ *
+ * NAMING CONVENTION:
+ * Files using this config MUST use: *.isolated.test.mts suffix
+ *
+ * PERFORMANCE TRADEOFF:
+ * - pool: 'forks' - Full process isolation (slower than threads)
+ * - Each test file runs in its own forked process
+ * - No shared state between test files
+ * - Automatically detected and run by scripts/test.mjs
+ *
+ * EXAMPLES:
+ * - test/purl-global-mocking.isolated.test.mts - Mocks global.URL constructor
+ *
+ * See main config (.config/vitest.config.mts) for standard concurrent tests.
  */
 import { defineConfig } from 'vitest/config'
 

.config/vitest.config.mts

@@ -1,3 +1,25 @@
+/**
+ * @fileoverview Main Vitest configuration for concurrent test execution.
+ *
+ * USE THIS CONFIG FOR:
+ * - Standard test files (*.test.mts)
+ * - Tests that don't modify global objects
+ * - Tests that don't require vi.doMock() or dynamic module mocking
+ * - All tests that can run concurrently without interference
+ *
+ * PERFORMANCE OPTIMIZATIONS:
+ * - pool: 'threads' - Fast worker threads vs slower process forks
+ * - isolate: false - Shared worker context for better nock/vi.mock() compatibility
+ * - concurrent: true - Tests run in parallel within suites
+ * - Adaptive thread count - More threads in dev, single thread for coverage
+ *
+ * FOR ISOLATED TESTS:
+ * Use .config/vitest.config.isolated.mts for tests requiring:
+ * - Global object mocking (global.URL, global.process, etc.)
+ * - vi.doMock() with dynamic module replacement
+ * - Full process isolation between tests
+ * - File naming: *.isolated.test.mts suffix
+ */
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 

CLAUDE.md

@@ -173,15 +173,40 @@ With `exactOptionalPropertyTypes`, assign conditionally:
 
 ### Testing
 
-**Vitest Configuration**: This repo uses the shared vitest configuration patterns documented in `../socket-registry/CLAUDE.md` (see "Vitest Configuration Variants" section). Three configs available:
-- `.config/vitest.config.mts` - Main config (default)
-- `.config/vitest.config.isolated.mts` - Full process isolation for vi.doMock()
+**Vitest Configuration**: This repo uses the shared vitest configuration patterns documented in `../socket-registry/CLAUDE.md` (see "Vitest Configuration Variants" section). Two configs available:
+- `.config/vitest.config.mts` - Main config (threads, isolate: false, concurrent: true)
+- `.config/vitest.config.isolated.mts` - Full process isolation (forks, isolate: true)
+
+#### Test File Naming Conventions
+🚨 **MANDATORY** - Use correct suffix based on isolation requirements:
+
+**Standard tests** (`*.test.mts`):
+- Run with thread pool, shared worker context
+- Fast execution, parallel within suites
+- Most tests should use this pattern
+- Example: `test/package-url.test.mts`
+
+**Isolated tests** (`*.isolated.test.mts`):
+- Run with fork pool, full process isolation
+- Required for tests that:
+  - Mock global objects (global.URL, global.process, etc.)
+  - Use vi.doMock() for dynamic module mocking
+  - Would cause race conditions in concurrent execution
+- Automatically detected and run separately by `scripts/test.mjs`
+- Example: `test/purl-global-mocking.isolated.test.mts`
+
+**When to use isolated tests**:
+- ✅ Modifying global.URL, global.process, or other globals
+- ✅ Tests that fail intermittently in concurrent mode
+- ❌ Standard property testing - use regular tests
+- ❌ HTTP mocking with nock - works fine in thread pool
 
 #### Test Structure
 - **Test files**: `test/` - All test files
 - **Spec compliance**: `test/purl-spec.test.mts` - Package URL spec tests
 - **Edge cases**: `test/purl-edge-cases.test.mts` - Edge cases and coverage
 - **Test helpers**: `test/utils/test-helpers.mts` - Reusable test utilities
+- **Assertion helpers**: `test/utils/assertions.mts` - Property validation helpers
 
 #### Test Helpers (`test/utils/test-helpers.mts`)
 

README.md

@@ -8,6 +8,31 @@
 
 TypeScript Package URL (purl) parser and builder. Drop-in replacement for [`packageurl-js`](https://socket.dev/npm/package/packageurl-js) with full type safety, zero dependencies, and spec compliance with the [Package URL specification](https://github.com/package-url/purl-spec).
 
+## What is a PURL?
+
+A Package URL (purl) standardizes how to identify software packages:
+
+```
+pkg:npm/[email protected]
+pkg:pypi/[email protected]
+pkg:maven/org.springframework/[email protected]
+```
+
+**Format breakdown**:
+```
+  pkg:type/namespace/name@version?qualifiers#subpath
+  │   │    │         │    │       │          │
+  │   │    │         │    │       │          └─ Optional subpath
+  │   │    │         │    │       └──────────── Optional key=value pairs
+  │   │    │         │    └──────────────────── Optional version
+  │   │    │         └───────────────────────── Required package name
+  │   │    └─────────────────────────────────── Optional namespace/scope
+  │   └──────────────────────────────────────── Required package type
+  └──────────────────────────────────────────── Scheme (always "pkg:")
+```
+
+**Supports 35+ ecosystems**: npm, pypi, maven, gem, cargo, nuget, composer, golang, docker, and more.
+
 ## Installation
 
 ```sh
@@ -100,11 +125,12 @@ function processPurl(type: EcosystemString) {
 
 ## Documentation
 
-**[→ API Reference](./docs/API.md)** - Complete API documentation
-
-**[→ Examples](./docs/EXAMPLES.md)** - Common use cases
-
-**[→ Builders](./docs/BUILDERS.md)** - Builder pattern guide
+| Doc | Description |
+|-----|-------------|
+| **[Getting Started](./docs/getting-started.md)** | Quick setup guide for contributors |
+| **[API Reference](./docs/api-reference.md)** | Complete API documentation |
+| **[Examples](./docs/usage-examples.md)** | Common use cases and patterns |
+| **[Builder Pattern](./docs/builder-pattern.md)** | Fluent builder guide |
 
 ## Development
 

docs/builder-pattern.md

@@ -15,10 +15,37 @@ const purl = PackageURLBuilder.npm()
   .build()
 ```
 
+**Visual flow**:
+```
+PackageURLBuilder
+      ↓
+  .npm()              ← Factory method sets type='npm'
+      ↓
+  .name('express')    ← Set required name
+      ↓
+  .version('4.18.0')  ← Set optional version
+      ↓
+  .build()            ← Returns PackageURL instance
+      ↓
+'pkg:npm/[email protected]'
+```
+
 ## Factory Methods
 
 Pre-configured builders for popular package ecosystems.
 
+| Ecosystem | Factory | Example Type |
+|-----------|---------|--------------|
+| JavaScript | `.npm()` | `pkg:npm/[email protected]` |
+| Python | `.pypi()` | `pkg:pypi/[email protected]` |
+| Java | `.maven()` | `pkg:maven/org.springframework/[email protected]` |
+| Ruby | `.gem()` | `pkg:gem/[email protected]` |
+| Rust | `.cargo()` | `pkg:cargo/[email protected]` |
+| .NET | `.nuget()` | `pkg:nuget/[email protected]` |
+| PHP | `.composer()` | `pkg:composer/symfony/[email protected]` |
+| Go | `.golang()` | `pkg:golang/github.com/gin-gonic/[email protected]` |
+| Docker | `.docker()` | `pkg:docker/[email protected]` |
+
 ### npm - JavaScript/Node.js
 
 ```typescript