docs(builders): add PurlBuilder fluent-API walkthrough

Covers when to use the builder vs the constructor, every setter
method, all 26 per-ecosystem static factories, qualifier
conventions, worked examples (package.json entry, download URL
qualifier, in-place field tweak, many qualifiers), validation
timing (fail-late-at-build), and the ESM/CJS instanceof footgun.

Junior-dev level: decision table up front for "which construction
style fits my situation", every code sample is self-contained and
shows both input and canonical output.

Author: jdalton

docs/builders.md

@@ -0,0 +1,296 @@
+# Builders
+
+The `PurlBuilder` fluent API — construct a `PackageURL` step by
+step, with per-field setters and per-ecosystem factories. Read
+this when you want to build a PURL from computed values rather
+than handing every argument to a constructor all at once.
+
+## Who this is for
+
+Callers with a runtime shape that doesn't fit a single constructor
+call — you have a loop, a conditional, or a pipeline where each
+piece of the PURL lands at a different step. Also contributors
+adding a new ecosystem factory.
+
+## When to use what
+
+| You have… | Use |
+|---|---|
+| All six pieces in hand at once | `new PackageURL(type, ns, name, version, qualifiers, subpath)` — positional, fastest. |
+| A loop / conditional that sets fields over time | `PurlBuilder` — method chaining, field-by-field. |
+| An existing PackageURL and want to tweak one field | `PurlBuilder.from(existing).name('new').build()` — creates a fresh instance since PackageURL is frozen. |
+| A string from the wire | `new PackageURL(str)` or `PackageURL.fromStringResult(str)` — see `docs/hardening.md`. |
+
+The builder is not faster than the constructor; it is easier to
+read when construction is spread across code.
+
+## The fluent API at a glance
+
+```typescript
+import { PurlBuilder } from '@socketregistry/packageurl-js'
+
+const purl = PurlBuilder.create()
+  .type('npm')
+  .namespace('@scope')
+  .name('left-pad')
+  .version('1.3.0')
+  .qualifier('extension', 'tgz')
+  .subpath('lib')
+  .build()
+
+purl.toString()
+// 'pkg:npm/%40scope/left-pad@1.3.0?extension=tgz#lib'
+```
+
+Every setter returns `this` so calls chain. `build()` returns the
+frozen `PackageURL` and validates — if a required field is missing
+or a value fails its component's validator, `build()` throws.
+
+## The setters
+
+| Method | Sets | Notes |
+|---|---|---|
+| `.type(str)` | The package type (`npm`, `pypi`, `maven`, …). Required. | Lowercased. Must match a registered `PurlType`. |
+| `.namespace(str)` | Namespace / scope / group (e.g. `@scope` for npm, `org.acme` for maven). Optional. | Normalization depends on type. npm lowercases; maven preserves case. |
+| `.name(str)` | Package name. Required. | Same as namespace — normalization per type. |
+| `.version(str)` | Version string. Optional. | Free-form; validated for injection chars but not semver-shape (ecosystems disagree). |
+| `.qualifier(key, value)` | One key-value qualifier. Add many by chaining multiple calls. | See the known-qualifier list below. |
+| `.qualifiers(obj)` | Set all qualifiers at once from an object. | Replaces any previously-set qualifiers. |
+| `.subpath(str)` | Subpath within the package (e.g. `lib/utils`). Optional. | Leading/trailing slashes are stripped. |
+| `.build()` | Finalize. | Throws on invalid. |
+
+## The per-ecosystem factories
+
+For common ecosystems, the builder has a static shortcut that pre-
+sets `.type()`:
+
+```typescript
+// These two are equivalent:
+PurlBuilder.create().type('npm').name('lodash').version('4.17.21').build()
+PurlBuilder.npm().name('lodash').version('4.17.21').build()
+```
+
+Available factories:
+
+| Factory | Ecosystem | Preset type |
+|---|---|---|
+| `PurlBuilder.bitbucket()` | Bitbucket repos | `bitbucket` |
+| `PurlBuilder.cargo()` | Rust crates | `cargo` |
+| `PurlBuilder.cocoapods()` | iOS/macOS pods | `cocoapods` |
+| `PurlBuilder.composer()` | PHP packages | `composer` |
+| `PurlBuilder.conan()` | C/C++ (Conan Center) | `conan` |
+| `PurlBuilder.conda()` | Conda packages | `conda` |
+| `PurlBuilder.cran()` | R packages | `cran` |
+| `PurlBuilder.deb()` | Debian packages | `deb` |
+| `PurlBuilder.docker()` | Docker images | `docker` |
+| `PurlBuilder.gem()` | Ruby gems | `gem` |
+| `PurlBuilder.github()` | GitHub repos | `github` |
+| `PurlBuilder.gitlab()` | GitLab repos | `gitlab` |
+| `PurlBuilder.golang()` | Go modules | `golang` |
+| `PurlBuilder.hackage()` | Haskell packages | `hackage` |
+| `PurlBuilder.hex()` | Elixir/Erlang packages | `hex` |
+| `PurlBuilder.huggingface()` | Hugging Face models | `huggingface` |
+| `PurlBuilder.luarocks()` | Lua packages | `luarocks` |
+| `PurlBuilder.maven()` | Maven Central | `maven` |
+| `PurlBuilder.npm()` | npm packages | `npm` |
+| `PurlBuilder.nuget()` | .NET packages | `nuget` |
+| `PurlBuilder.oci()` | OCI containers | `oci` |
+| `PurlBuilder.pub()` | Dart/Flutter | `pub` |
+| `PurlBuilder.pypi()` | Python packages | `pypi` |
+| `PurlBuilder.rpm()` | RPM packages | `rpm` |
+| `PurlBuilder.swift()` | Swift packages | `swift` |
+
+Generic entry points:
+
+- `PurlBuilder.create()` — no type preset. You must call `.type()`
+  before `.build()`.
+- `PurlBuilder.from(existing: PackageURL)` — seeds every field from
+  an existing `PackageURL`. Useful for "take this PURL but change
+  one field."
+
+## Known qualifier keys
+
+Qualifiers are an open key-value space, but the PURL spec (and
+downstream tooling) standardizes a few:
+
+| Qualifier | Meaning |
+|---|---|
+| `checksum` | Digest of the artifact (e.g. `sha256:abc…`). |
+| `download_url` | Direct URL to download the artifact. |
+| `file_name` | Filename of the distributed artifact (e.g. `tar.gz`, `whl`). |
+| `repository_url` | URL of the source repository. |
+| `vcs_url` | VCS (git/hg) URL, including commit reference. |
+| `vers` | A VERS range (see `docs/vers.md`) constraining the version. |
+
+The library knows these keys and normalizes their values; custom
+keys pass through untouched. See
+`src/purl-qualifier-names.ts` for the canonical list.
+
+## Worked examples
+
+### Build from a package.json entry
+
+```typescript
+function purlFromPackageJson(name: string, version: string): PackageURL {
+  const builder = PurlBuilder.npm().version(version)
+
+  // npm scoped packages: '@scope/pkg' → namespace '@scope', name 'pkg'
+  if (name.startsWith('@')) {
+    const [scope, pkg] = name.split('/')
+    builder.namespace(scope).name(pkg)
+  } else {
+    builder.name(name)
+  }
+
+  return builder.build()
+}
+
+purlFromPackageJson('lodash', '4.17.21').toString()
+// 'pkg:npm/lodash@4.17.21'
+
+purlFromPackageJson('@scope/pkg', '1.0.0').toString()
+// 'pkg:npm/%40scope/pkg@1.0.0'
+```
+
+### Build with a download URL qualifier
+
+```typescript
+const purl = PurlBuilder.pypi()
+  .name('requests')
+  .version('2.31.0')
+  .qualifier('extension', 'tar.gz')
+  .qualifier('download_url', 'https://files.pythonhosted.org/…/requests-2.31.0.tar.gz')
+  .build()
+
+purl.toString()
+// 'pkg:pypi/requests@2.31.0?download_url=…&extension=tar.gz'
+```
+
+Note that qualifiers are alphabetized in the canonical output.
+
+### Tweak one field on an existing PURL
+
+```typescript
+const original = new PackageURL('npm', undefined, 'lodash', '4.17.20')
+const updated = PurlBuilder.from(original).version('4.17.21').build()
+
+original.toString()  // 'pkg:npm/lodash@4.17.20' (unchanged; frozen)
+updated.toString()   // 'pkg:npm/lodash@4.17.21'
+```
+
+`PurlBuilder.from()` is the only sanctioned way to produce a
+modified copy. Direct mutation is impossible by design (see
+`docs/hardening.md`).
+
+### Chain many qualifiers
+
+```typescript
+PurlBuilder.maven()
+  .namespace('org.apache.logging.log4j')
+  .name('log4j-core')
+  .version('2.17.1')
+  .qualifier('classifier', 'sources')
+  .qualifier('extension', 'jar')
+  .qualifier('type', 'sources')
+  .qualifier('repository_url', 'https://repo.maven.apache.org/maven2')
+  .build()
+```
+
+Alternative using `.qualifiers(obj)`:
+
+```typescript
+PurlBuilder.maven()
+  .namespace('org.apache.logging.log4j')
+  .name('log4j-core')
+  .version('2.17.1')
+  .qualifiers({
+    classifier: 'sources',
+    extension: 'jar',
+    type: 'sources',
+    repository_url: 'https://repo.maven.apache.org/maven2',
+  })
+  .build()
+```
+
+Both produce the same PURL. Use `.qualifier()` when adding one at
+a time inside a loop; use `.qualifiers()` when you have the whole
+object already.
+
+## Validation timing
+
+The builder does **not** validate as you set — so:
+
+```typescript
+PurlBuilder.create()
+  .type('npm')
+  .name('')       // empty name — won't error here
+```
+
+Validation runs when you call `.build()`. That call constructs a
+new `PackageURL`, which invokes the per-component validators. A
+failure at `.build()` throws with a message pointing at the
+offending field.
+
+This "fail late" design lets you construct a builder in one place
+and pass it around (e.g. to helper functions that set more fields)
+without each mutation being a potential throw site. If you want
+"fail early," prefer the constructor and check the throw at a
+single site.
+
+## The ESM/CJS `instanceof` footgun
+
+`PurlBuilder` internally imports `PackageURL` via CommonJS
+`require()`. If your code imports `PackageURL` via ESM `import`,
+Node wraps the two imports into different objects, and
+`builtPurl instanceof PackageURL` returns `false` even though the
+structure is correct.
+
+Workaround:
+
+```typescript
+// Bad:
+const ok = purl instanceof PackageURL
+
+// Good:
+const ok = purl && purl.constructor.name === 'PackageURL'
+
+// Also good — use a duck-type check on the fields you care about:
+const ok = typeof purl === 'object' && typeof purl.toString === 'function'
+```
+
+This limitation is a Node ESM/CJS interop artifact, not a library
+bug. Affects only `instanceof`, not any actual functionality.
+
+## Adding a new ecosystem factory
+
+If you implement a new `PurlType` handler under
+`src/purl-types/<name>.ts`, add a matching `PurlBuilder.<name>()`
+factory:
+
+```typescript
+static <name>(): PurlBuilder {
+  return new PurlBuilder().type('<name>')
+}
+```
+
+Conventions:
+
+- Method name: ecosystem name, lowercase.
+- Body: `new PurlBuilder().type('<name>')`. No other presets.
+- Doc comment: one-line description matching the
+  per-ecosystem-factory table above.
+- Alphabetical order in the class.
+
+## Further reading
+
+- [`docs/architecture.md`](./architecture.md) — where the builder
+  sits in the module map.
+- [`docs/converters.md`](./converters.md) — builder's cousin for
+  URL ↔ PURL round-trips.
+- [`docs/hardening.md`](./hardening.md) — why built instances are
+  frozen.
+- [`docs/api.md`](./api.md) — full API reference.
+- [`src/package-url-builder.ts`](../src/package-url-builder.ts) —
+  the implementation.
+- [`src/purl-qualifier-names.ts`](../src/purl-qualifier-names.ts) —
+  canonical list of known qualifier keys.

tour.json

@@ -173,6 +173,12 @@
       "source": "docs/architecture.md",
       "summary": "Module map, data flow, and the key abstractions that keep the library small."
     },
+    {
+      "filename": "builders",
+      "title": "Builders",
+      "source": "docs/builders.md",
+      "summary": "The PurlBuilder fluent API — construct a PackageURL step by step with per-field setters and per-ecosystem factories."
+    },
     {
       "filename": "hardening",
       "title": "Hardening",