Skip to content

Commit b875767

Browse files
jdaltonjdalton
committed
style(docs): oxfmt table alignment normalization
Running oxfmt picked up aligned table column widths across the 7 docs landed this week. No content changes.
1 parent fb41529 commit b875767

7 files changed

Lines changed: 164 additions & 157 deletions

File tree

‎docs/architecture.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,14 @@ Two entry points:
150150
**Constructor** (all-at-once):
151151

152152
```typescript
153-
new PackageURL('npm', '@scope', 'left-pad', '1.3.0', { extension: 'tgz' }, 'lib')
153+
new PackageURL(
154+
'npm',
155+
'@scope',
156+
'left-pad',
157+
'1.3.0',
158+
{ extension: 'tgz' },
159+
'lib',
160+
)
154161
```
155162

156163
**Builder** (fluent):
@@ -292,7 +299,7 @@ Two error classes:
292299
- **`PurlInjectionError`** — the input contained a dangerous
293300
control character that could desync a downstream consumer (URL
294301
encoder, shell interpolation, SQL). Thrown before parse — we
295-
refuse to even *interpret* input that could smuggle injection
302+
refuse to even _interpret_ input that could smuggle injection
296303
payloads.
297304

298305
See `docs/safety.md` for the threat model.

‎docs/builders.md‎

Lines changed: 57 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,12 @@ adding a new ecosystem factory.
1414

1515
## When to use what
1616

17-
| You have… | Use |
18-
|---|---|
19-
| All six pieces in hand at once | `new PackageURL(type, ns, name, version, qualifiers, subpath)` — positional, fastest. |
20-
| A loop / conditional that sets fields over time | `PurlBuilder` — method chaining, field-by-field. |
17+
| You have… | Use |
18+
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
19+
| All six pieces in hand at once | `new PackageURL(type, ns, name, version, qualifiers, subpath)` — positional, fastest. |
20+
| A loop / conditional that sets fields over time | `PurlBuilder` — method chaining, field-by-field. |
2121
| An existing PackageURL and want to tweak one field | `PurlBuilder.from(existing).name('new').build()` — creates a fresh instance since PackageURL is frozen. |
22-
| A string from the wire | `new PackageURL(str)` or `PackageURL.fromStringResult(str)` — see `docs/hardening.md`. |
22+
| A string from the wire | `new PackageURL(str)` or `PackageURL.fromStringResult(str)` — see `docs/hardening.md`. |
2323

2424
The builder is not faster than the constructor; it is easier to
2525
read when construction is spread across code.
@@ -48,16 +48,16 @@ or a value fails its component's validator, `build()` throws.
4848

4949
## The setters
5050

51-
| Method | Sets | Notes |
52-
|---|---|---|
53-
| `.type(str)` | The package type (`npm`, `pypi`, `maven`, …). Required. | Lowercased. Must match a registered `PurlType`. |
54-
| `.namespace(str)` | Namespace / scope / group (e.g. `@scope` for npm, `org.acme` for maven). Optional. | Normalization depends on type. npm lowercases; maven preserves case. |
55-
| `.name(str)` | Package name. Required. | Same as namespace — normalization per type. |
56-
| `.version(str)` | Version string. Optional. | Free-form; validated for injection chars but not semver-shape (ecosystems disagree). |
57-
| `.qualifier(key, value)` | One key-value qualifier. Add many by chaining multiple calls. | See the known-qualifier list below. |
58-
| `.qualifiers(obj)` | Set all qualifiers at once from an object. | Replaces any previously-set qualifiers. |
59-
| `.subpath(str)` | Subpath within the package (e.g. `lib/utils`). Optional. | Leading/trailing slashes are stripped. |
60-
| `.build()` | Finalize. | Throws on invalid. |
51+
| Method | Sets | Notes |
52+
| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
53+
| `.type(str)` | The package type (`npm`, `pypi`, `maven`, …). Required. | Lowercased. Must match a registered `PurlType`. |
54+
| `.namespace(str)` | Namespace / scope / group (e.g. `@scope` for npm, `org.acme` for maven). Optional. | Normalization depends on type. npm lowercases; maven preserves case. |
55+
| `.name(str)` | Package name. Required. | Same as namespace — normalization per type. |
56+
| `.version(str)` | Version string. Optional. | Free-form; validated for injection chars but not semver-shape (ecosystems disagree). |
57+
| `.qualifier(key, value)` | One key-value qualifier. Add many by chaining multiple calls. | See the known-qualifier list below. |
58+
| `.qualifiers(obj)` | Set all qualifiers at once from an object. | Replaces any previously-set qualifiers. |
59+
| `.subpath(str)` | Subpath within the package (e.g. `lib/utils`). Optional. | Leading/trailing slashes are stripped. |
60+
| `.build()` | Finalize. | Throws on invalid. |
6161

6262
## The per-ecosystem factories
6363

@@ -72,33 +72,33 @@ PurlBuilder.npm().name('lodash').version('4.17.21').build()
7272

7373
Available factories:
7474

75-
| Factory | Ecosystem | Preset type |
76-
|---|---|---|
77-
| `PurlBuilder.bitbucket()` | Bitbucket repos | `bitbucket` |
78-
| `PurlBuilder.cargo()` | Rust crates | `cargo` |
79-
| `PurlBuilder.cocoapods()` | iOS/macOS pods | `cocoapods` |
80-
| `PurlBuilder.composer()` | PHP packages | `composer` |
81-
| `PurlBuilder.conan()` | C/C++ (Conan Center) | `conan` |
82-
| `PurlBuilder.conda()` | Conda packages | `conda` |
83-
| `PurlBuilder.cran()` | R packages | `cran` |
84-
| `PurlBuilder.deb()` | Debian packages | `deb` |
85-
| `PurlBuilder.docker()` | Docker images | `docker` |
86-
| `PurlBuilder.gem()` | Ruby gems | `gem` |
87-
| `PurlBuilder.github()` | GitHub repos | `github` |
88-
| `PurlBuilder.gitlab()` | GitLab repos | `gitlab` |
89-
| `PurlBuilder.golang()` | Go modules | `golang` |
90-
| `PurlBuilder.hackage()` | Haskell packages | `hackage` |
91-
| `PurlBuilder.hex()` | Elixir/Erlang packages | `hex` |
92-
| `PurlBuilder.huggingface()` | Hugging Face models | `huggingface` |
93-
| `PurlBuilder.luarocks()` | Lua packages | `luarocks` |
94-
| `PurlBuilder.maven()` | Maven Central | `maven` |
95-
| `PurlBuilder.npm()` | npm packages | `npm` |
96-
| `PurlBuilder.nuget()` | .NET packages | `nuget` |
97-
| `PurlBuilder.oci()` | OCI containers | `oci` |
98-
| `PurlBuilder.pub()` | Dart/Flutter | `pub` |
99-
| `PurlBuilder.pypi()` | Python packages | `pypi` |
100-
| `PurlBuilder.rpm()` | RPM packages | `rpm` |
101-
| `PurlBuilder.swift()` | Swift packages | `swift` |
75+
| Factory | Ecosystem | Preset type |
76+
| --------------------------- | ---------------------- | ------------- |
77+
| `PurlBuilder.bitbucket()` | Bitbucket repos | `bitbucket` |
78+
| `PurlBuilder.cargo()` | Rust crates | `cargo` |
79+
| `PurlBuilder.cocoapods()` | iOS/macOS pods | `cocoapods` |
80+
| `PurlBuilder.composer()` | PHP packages | `composer` |
81+
| `PurlBuilder.conan()` | C/C++ (Conan Center) | `conan` |
82+
| `PurlBuilder.conda()` | Conda packages | `conda` |
83+
| `PurlBuilder.cran()` | R packages | `cran` |
84+
| `PurlBuilder.deb()` | Debian packages | `deb` |
85+
| `PurlBuilder.docker()` | Docker images | `docker` |
86+
| `PurlBuilder.gem()` | Ruby gems | `gem` |
87+
| `PurlBuilder.github()` | GitHub repos | `github` |
88+
| `PurlBuilder.gitlab()` | GitLab repos | `gitlab` |
89+
| `PurlBuilder.golang()` | Go modules | `golang` |
90+
| `PurlBuilder.hackage()` | Haskell packages | `hackage` |
91+
| `PurlBuilder.hex()` | Elixir/Erlang packages | `hex` |
92+
| `PurlBuilder.huggingface()` | Hugging Face models | `huggingface` |
93+
| `PurlBuilder.luarocks()` | Lua packages | `luarocks` |
94+
| `PurlBuilder.maven()` | Maven Central | `maven` |
95+
| `PurlBuilder.npm()` | npm packages | `npm` |
96+
| `PurlBuilder.nuget()` | .NET packages | `nuget` |
97+
| `PurlBuilder.oci()` | OCI containers | `oci` |
98+
| `PurlBuilder.pub()` | Dart/Flutter | `pub` |
99+
| `PurlBuilder.pypi()` | Python packages | `pypi` |
100+
| `PurlBuilder.rpm()` | RPM packages | `rpm` |
101+
| `PurlBuilder.swift()` | Swift packages | `swift` |
102102

103103
Generic entry points:
104104

@@ -113,14 +113,14 @@ Generic entry points:
113113
Qualifiers are an open key-value space, but the PURL spec (and
114114
downstream tooling) standardizes a few:
115115

116-
| Qualifier | Meaning |
117-
|---|---|
118-
| `checksum` | Digest of the artifact (e.g. `sha256:abc…`). |
119-
| `download_url` | Direct URL to download the artifact. |
120-
| `file_name` | Filename of the distributed artifact (e.g. `tar.gz`, `whl`). |
121-
| `repository_url` | URL of the source repository. |
122-
| `vcs_url` | VCS (git/hg) URL, including commit reference. |
123-
| `vers` | A VERS range (see `docs/vers.md`) constraining the version. |
116+
| Qualifier | Meaning |
117+
| ---------------- | ------------------------------------------------------------ |
118+
| `checksum` | Digest of the artifact (e.g. `sha256:abc…`). |
119+
| `download_url` | Direct URL to download the artifact. |
120+
| `file_name` | Filename of the distributed artifact (e.g. `tar.gz`, `whl`). |
121+
| `repository_url` | URL of the source repository. |
122+
| `vcs_url` | VCS (git/hg) URL, including commit reference. |
123+
| `vers` | A VERS range (see `docs/vers.md`) constraining the version. |
124124

125125
The library knows these keys and normalizes their values; custom
126126
keys pass through untouched. See
@@ -159,7 +159,10 @@ const purl = PurlBuilder.pypi()
159159
.name('requests')
160160
.version('2.31.0')
161161
.qualifier('extension', 'tar.gz')
162-
.qualifier('download_url', 'https://files.pythonhosted.org/…/requests-2.31.0.tar.gz')
162+
.qualifier(
163+
'download_url',
164+
'https://files.pythonhosted.org/…/requests-2.31.0.tar.gz',
165+
)
163166
.build()
164167

165168
purl.toString()
@@ -174,8 +177,8 @@ Note that qualifiers are alphabetized in the canonical output.
174177
const original = new PackageURL('npm', undefined, 'lodash', '4.17.20')
175178
const updated = PurlBuilder.from(original).version('4.17.21').build()
176179

177-
original.toString() // 'pkg:npm/lodash@4.17.20' (unchanged; frozen)
178-
updated.toString() // 'pkg:npm/lodash@4.17.21'
180+
original.toString() // 'pkg:npm/lodash@4.17.20' (unchanged; frozen)
181+
updated.toString() // 'pkg:npm/lodash@4.17.21'
179182
```
180183

181184
`PurlBuilder.from()` is the only sanctioned way to produce a
@@ -221,9 +224,7 @@ object already.
221224
The builder does **not** validate as you set — so:
222225

223226
```typescript
224-
PurlBuilder.create()
225-
.type('npm')
226-
.name('') // empty name — won't error here
227+
PurlBuilder.create().type('npm').name('') // empty name — won't error here
227228
```
228229

229230
Validation runs when you call `.build()`. That call constructs a

‎docs/contributing.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ change → Running checks → Opening the PR**.
1414

1515
Requirements:
1616

17-
| Tool | Version | Notes |
18-
|---|---|---|
19-
| Node.js | ≥ 22 | Built-in TypeScript stripping (`--experimental-strip-types` on 22, default on 23+). |
20-
| pnpm | ≥ 11.0.0-rc.0 | Install via `corepack enable pnpm` or `npm install -g pnpm`. |
21-
| git | ≥ 2.30 | Submodule support. |
17+
| Tool | Version | Notes |
18+
| ------- | ------------- | ----------------------------------------------------------------------------------- |
19+
| Node.js | ≥ 22 | Built-in TypeScript stripping (`--experimental-strip-types` on 22, default on 23+). |
20+
| pnpm | ≥ 11.0.0-rc.0 | Install via `corepack enable pnpm` or `npm install -g pnpm`. |
21+
| git | ≥ 2.30 | Submodule support. |
2222

2323
Clone and install:
2424

@@ -99,9 +99,9 @@ Per `CLAUDE.md`:
9999

100100
Two vitest configs:
101101

102-
| Config | When | File naming |
103-
|---|---|---|
104-
| `.config/vitest.config.mts` | Normal tests. Threads, shared memory. Fast. | `*.test.mts` |
102+
| Config | When | File naming |
103+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- | --------------------- |
104+
| `.config/vitest.config.mts` | Normal tests. Threads, shared memory. Fast. | `*.test.mts` |
105105
| `.config/vitest.config.isolated.mts` | Tests that mock globals via `vi.doMock`, modify `process.env`, or `process.chdir`. Forks, full isolation. | `*.isolated.test.mts` |
106106

107107
**Test style in this repo:** functional. Tests assert behavior via
@@ -143,18 +143,18 @@ It runs:
143143

144144
Every step runs independently too:
145145

146-
| Command | What |
147-
|---|---|
148-
| `pnpm build` | Compile `src/` → `dist/` (esbuild). `pnpm build --watch` for dev. |
149-
| `pnpm type` | Strict TypeScript check, no emit. |
150-
| `pnpm lint` | oxlint. |
151-
| `pnpm fix` | Auto-fix what's auto-fixable (formatter + lint autofixes). |
152-
| `pnpm test` | Run vitest. `pnpm test:unit path/to/file.test.mts` for a single file. Never use `--` before test paths — runs ALL tests. |
153-
| `pnpm testu` | Update vitest snapshots (review the diff before committing). |
154-
| `pnpm cover` | Coverage. Must stay at 100%. |
155-
| `pnpm format` | Run oxfmt across the tree (writes fixes). |
156-
| `pnpm format --check` | Verify formatting without writing. |
157-
| `pnpm security` | AgentShield + zizmor security scan. |
146+
| Command | What |
147+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
148+
| `pnpm build` | Compile `src/` → `dist/` (esbuild). `pnpm build --watch` for dev. |
149+
| `pnpm type` | Strict TypeScript check, no emit. |
150+
| `pnpm lint` | oxlint. |
151+
| `pnpm fix` | Auto-fix what's auto-fixable (formatter + lint autofixes). |
152+
| `pnpm test` | Run vitest. `pnpm test:unit path/to/file.test.mts` for a single file. Never use `--` before test paths — runs ALL tests. |
153+
| `pnpm testu` | Update vitest snapshots (review the diff before committing). |
154+
| `pnpm cover` | Coverage. Must stay at 100%. |
155+
| `pnpm format` | Run oxfmt across the tree (writes fixes). |
156+
| `pnpm format --check` | Verify formatting without writing. |
157+
| `pnpm security` | AgentShield + zizmor security scan. |
158158

159159
### Coverage — the 100% rule
160160

‎docs/converters.md‎

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -46,33 +46,33 @@ When you call `UrlConverter.fromUrl('https://github.com/lodash/lodash')`
4646
the library dispatches on the URL's hostname. These hostnames are
4747
registered:
4848

49-
| Hostname | Dispatches to |
50-
|---|---|
51-
| `registry.npmjs.org` | npm registry API parser |
52-
| `www.npmjs.com` | npm website parser (human-facing URLs) |
53-
| `pypi.org` | pypi |
54-
| `repo1.maven.org`, `central.maven.org` | maven |
55-
| `rubygems.org` | gem |
56-
| `crates.io` | cargo |
57-
| `www.nuget.org`, `api.nuget.org` | nuget |
58-
| `pkg.go.dev` | golang |
59-
| `hex.pm` | hex (Elixir/Erlang) |
60-
| `pub.dev` | pub (Dart/Flutter) |
61-
| `packagist.org` | composer (PHP) |
62-
| `hub.docker.com` | docker |
63-
| `cocoapods.org` | cocoapods |
64-
| `hackage.haskell.org` | hackage |
65-
| `cran.r-project.org` | cran |
66-
| `anaconda.org` | conda |
67-
| `metacpan.org` | cpan |
68-
| `luarocks.org` | luarocks |
69-
| `swiftpackageindex.com` | swift |
70-
| `huggingface.co` | huggingface |
71-
| `marketplace.visualstudio.com` | vscode-extension |
72-
| `open-vsx.org` | vscode-extension |
73-
| `github.com` | github (repo PURL) |
74-
| `gitlab.com` | gitlab |
75-
| `bitbucket.org` | bitbucket |
49+
| Hostname | Dispatches to |
50+
| -------------------------------------- | -------------------------------------- |
51+
| `registry.npmjs.org` | npm registry API parser |
52+
| `www.npmjs.com` | npm website parser (human-facing URLs) |
53+
| `pypi.org` | pypi |
54+
| `repo1.maven.org`, `central.maven.org` | maven |
55+
| `rubygems.org` | gem |
56+
| `crates.io` | cargo |
57+
| `www.nuget.org`, `api.nuget.org` | nuget |
58+
| `pkg.go.dev` | golang |
59+
| `hex.pm` | hex (Elixir/Erlang) |
60+
| `pub.dev` | pub (Dart/Flutter) |
61+
| `packagist.org` | composer (PHP) |
62+
| `hub.docker.com` | docker |
63+
| `cocoapods.org` | cocoapods |
64+
| `hackage.haskell.org` | hackage |
65+
| `cran.r-project.org` | cran |
66+
| `anaconda.org` | conda |
67+
| `metacpan.org` | cpan |
68+
| `luarocks.org` | luarocks |
69+
| `swiftpackageindex.com` | swift |
70+
| `huggingface.co` | huggingface |
71+
| `marketplace.visualstudio.com` | vscode-extension |
72+
| `open-vsx.org` | vscode-extension |
73+
| `github.com` | github (repo PURL) |
74+
| `gitlab.com` | gitlab |
75+
| `bitbucket.org` | bitbucket |
7676

7777
`UrlConverter.supportsFromUrl(str)` answers "is this URL
7878
recognized?" without parsing.
@@ -173,10 +173,9 @@ For some ecosystems, the repository URL depends on qualifiers set
173173
on the PURL:
174174

175175
```typescript
176-
const pypiWithRepo = new PackageURL(
177-
'pypi', undefined, 'requests', '2.31.0',
178-
{ repository_url: 'https://github.com/psf/requests' }
179-
)
176+
const pypiWithRepo = new PackageURL('pypi', undefined, 'requests', '2.31.0', {
177+
repository_url: 'https://github.com/psf/requests',
178+
})
180179
UrlConverter.toRepositoryUrl(pypiWithRepo)
181180
// → { type: 'git', url: 'https://github.com/psf/requests.git' }
182181
```

0 commit comments

Comments
 (0)