Skip to content

Commit accc291

Browse files
jdaltonjdalton
committed
walkthrough: expand from 1 part to 8 — full library coverage
Previously the walkthrough shipped one part (Anatomy of a PURL, 41 sections across 3 files). The library is much bigger than that — this extends the plan to cover every public feature. Eight parts, ordered by reader journey: 1. Anatomy of a PURL — (unchanged) package-url.ts, purl-component.ts, constants.ts. 41 sections. 2. Building & Stringifying — package-url-builder.ts, stringify.ts. Fluent PurlBuilder API + canonical pkg:... emission. 46 sections. 3. Parsing & Normalization — encode.ts, decode.ts, normalize.ts, purl-qualifier-names.ts. Percent-encoding, name/namespace rules, known-qualifier catalogue. 24 sections. 4. Validation, Errors & Results — validate.ts, result.ts, error.ts, purl-type.ts. Shape/format validation, Result<T,E> pattern (Ok/Err/ResultUtils), typed errors (PurlError, PurlInjectionError), per-ecosystem rule plumbing. 56 sections. 5. URL ↔ PURL Conversion — url-converter.ts. All ~25 ecosystem URL parsers, toDownloadUrl, toRepositoryUrl, getAllUrls. 65 sections. 6. Ecosystems — all 41 files in src/purl-types/ (alpm through yocto). Per-ecosystem normalize/validate/encode rules. 181 sections. 7. Comparison, Matching & Existence — compare.ts, exists.ts, purl-exists.ts, helpers.ts. Wildcard matching with ReDoS guard, registry existence checks. 20 sections. 8. Security Primitives & VERS — strings.ts, objects.ts, vers.ts. Injection-character detection, safe freezing, and VERS — the pre-standard version-range specifier slated for Ecma submission in late 2026. 35 sections. Total: 468 annotated sections across the library. Every part page has the complete 8-part nav in the topbar. Index page lists all 8 with section counts. SRI, CSP, base-path rewriting, malware audit, and auto-deploy-to-Val-Town pipelines all handle N parts without changes.
1 parent 4948b38 commit accc291

1 file changed

Lines changed: 156 additions & 0 deletions

File tree

‎walkthrough.json‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,162 @@
1313
"src/purl-component.ts",
1414
"src/constants.ts"
1515
]
16+
},
17+
{
18+
"id": 2,
19+
"title": "Building & Stringifying PURLs",
20+
"objective": "Build PURLs with the fluent PurlBuilder API; serialize back to canonical `pkg:...` string form.",
21+
"keywords": [
22+
"builder",
23+
"fluent",
24+
"stringify",
25+
"serialization",
26+
"canonical"
27+
],
28+
"files": ["src/package-url-builder.ts", "src/stringify.ts"]
29+
},
30+
{
31+
"id": 3,
32+
"title": "Parsing & Normalization",
33+
"objective": "Percent-encoding, name/namespace normalization, and the known-qualifiers catalogue (checksum, download_url, file_name, repository_url, vcs_url, vers).",
34+
"keywords": [
35+
"encode",
36+
"decode",
37+
"percent-encoding",
38+
"normalize",
39+
"qualifiers"
40+
],
41+
"files": [
42+
"src/encode.ts",
43+
"src/decode.ts",
44+
"src/normalize.ts",
45+
"src/purl-qualifier-names.ts"
46+
]
47+
},
48+
{
49+
"id": 4,
50+
"title": "Validation, Errors & Results",
51+
"objective": "Shape + format validation, the Result<T,E> functional error pattern (Ok/Err/ResultUtils), typed errors (PurlError, PurlInjectionError), and per-ecosystem rule plumbing.",
52+
"keywords": [
53+
"validate",
54+
"result",
55+
"error",
56+
"ok",
57+
"err",
58+
"purl-type"
59+
],
60+
"files": [
61+
"src/validate.ts",
62+
"src/result.ts",
63+
"src/error.ts",
64+
"src/purl-type.ts"
65+
]
66+
},
67+
{
68+
"id": 5,
69+
"title": "URL ↔ PURL Conversion",
70+
"objective": "Convert between repository/download URLs and PURLs — ~25 ecosystem URL parsers, toDownloadUrl, toRepositoryUrl, getAllUrls.",
71+
"keywords": [
72+
"url-converter",
73+
"url",
74+
"repository",
75+
"download",
76+
"vcs"
77+
],
78+
"files": ["src/url-converter.ts"]
79+
},
80+
{
81+
"id": 6,
82+
"title": "Ecosystems",
83+
"objective": "Per-ecosystem normalize/validate/encode rules across all 41 supported package ecosystems.",
84+
"keywords": [
85+
"ecosystem",
86+
"purl-types",
87+
"npm",
88+
"maven",
89+
"cargo",
90+
"docker",
91+
"pypi",
92+
"deb",
93+
"rpm",
94+
"github"
95+
],
96+
"files": [
97+
"src/purl-types/alpm.ts",
98+
"src/purl-types/apk.ts",
99+
"src/purl-types/bazel.ts",
100+
"src/purl-types/bitbucket.ts",
101+
"src/purl-types/bitnami.ts",
102+
"src/purl-types/cargo.ts",
103+
"src/purl-types/cocoapods.ts",
104+
"src/purl-types/composer.ts",
105+
"src/purl-types/conan.ts",
106+
"src/purl-types/conda.ts",
107+
"src/purl-types/cpan.ts",
108+
"src/purl-types/cran.ts",
109+
"src/purl-types/deb.ts",
110+
"src/purl-types/docker.ts",
111+
"src/purl-types/gem.ts",
112+
"src/purl-types/generic.ts",
113+
"src/purl-types/github.ts",
114+
"src/purl-types/gitlab.ts",
115+
"src/purl-types/golang.ts",
116+
"src/purl-types/hackage.ts",
117+
"src/purl-types/hex.ts",
118+
"src/purl-types/huggingface.ts",
119+
"src/purl-types/julia.ts",
120+
"src/purl-types/luarocks.ts",
121+
"src/purl-types/maven.ts",
122+
"src/purl-types/mlflow.ts",
123+
"src/purl-types/npm.ts",
124+
"src/purl-types/nuget.ts",
125+
"src/purl-types/oci.ts",
126+
"src/purl-types/opam.ts",
127+
"src/purl-types/otp.ts",
128+
"src/purl-types/pub.ts",
129+
"src/purl-types/pypi.ts",
130+
"src/purl-types/qpkg.ts",
131+
"src/purl-types/rpm.ts",
132+
"src/purl-types/socket.ts",
133+
"src/purl-types/swid.ts",
134+
"src/purl-types/swift.ts",
135+
"src/purl-types/unknown.ts",
136+
"src/purl-types/vscode-extension.ts",
137+
"src/purl-types/yocto.ts"
138+
]
139+
},
140+
{
141+
"id": 7,
142+
"title": "Comparison, Matching & Existence",
143+
"objective": "Compare + equal + match PURLs with wildcard patterns (ReDoS-protected); registry existence checks (npmExists, pypiExists, and friends).",
144+
"keywords": [
145+
"compare",
146+
"equals",
147+
"matches",
148+
"wildcard",
149+
"exists",
150+
"registry"
151+
],
152+
"files": [
153+
"src/compare.ts",
154+
"src/exists.ts",
155+
"src/purl-exists.ts",
156+
"src/helpers.ts"
157+
]
158+
},
159+
{
160+
"id": 8,
161+
"title": "Security Primitives & VERS",
162+
"objective": "Injection-character detection for safe PURL handling (containsInjectionCharacters, findInjectionCharCode), safe object freezing, and VERS — the pre-standard version-range specifier slated for Ecma submission in late 2026.",
163+
"keywords": [
164+
"security",
165+
"injection",
166+
"freeze",
167+
"vers",
168+
"version-range",
169+
"pre-standard"
170+
],
171+
"files": ["src/strings.ts", "src/objects.ts", "src/vers.ts"]
16172
}
17173
]
18174
}

0 commit comments

Comments
 (0)