Skip to content

Commit 8c8639f

Browse files
committed
docs: update and consolidate documentation
- Align CLAUDE.md with canonical standards - Reduce verbosity in documentation - Consolidate getting started documentation - Remove redundant documentation (builder-pattern, api-reference, usage-examples) - Consolidate coverage badges to match socket-lib format - Add coverage badges and onboarding guide
1 parent 7fdfde6 commit 8c8639f

File tree

6 files changed

+53
-2397
lines changed

6 files changed

+53
-2397
lines changed

CLAUDE.md

Lines changed: 44 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# CLAUDE.md
22

3-
🚨 **MANDATORY**: Act as principal-level engineer with deep expertise in JavaScript, Node.js, and package URL parsing.
3+
**MANDATORY**: Act as principal-level engineer. Follow these guidelines exactly.
4+
5+
## CANONICAL REFERENCE
6+
7+
This is a reference to shared Socket standards. See `../socket-registry/CLAUDE.md` for canonical source.
48

59
## 👤 USER CONTEXT
610

@@ -11,6 +15,33 @@
1115
- **Example**: If git shows "John-David Dalton <[email protected]>", refer to them as "John-David"
1216
- **Other contributors**: Use their actual names from commit history/context
1317

18+
## PRE-ACTION PROTOCOL
19+
20+
**MANDATORY**: Review CLAUDE.md before any action. No exceptions.
21+
22+
## VERIFICATION PROTOCOL
23+
24+
**MANDATORY**: Before claiming any task is complete:
25+
1. Test the solution end-to-end
26+
2. Verify all changes work as expected
27+
3. Run the actual commands to confirm functionality
28+
4. Never claim "Done" without verification
29+
30+
## ABSOLUTE RULES
31+
32+
- Never create files unless necessary
33+
- Always prefer editing existing files
34+
- Forbidden to create docs unless requested
35+
- Required to do exactly what was asked
36+
37+
## ROLE
38+
39+
Principal Software Engineer: production code, architecture, reliability, ownership.
40+
41+
## EVOLUTION
42+
43+
If user repeats instruction 2+ times, ask: "Should I add this to CLAUDE.md?"
44+
1445
## 📚 SHARED STANDARDS
1546

1647
**Canonical reference**: `../socket-registry/CLAUDE.md`
@@ -22,6 +53,9 @@ All shared standards (git, testing, code style, cross-platform, CI) defined in s
2253
- Scripts: Prefer `pnpm run foo --flag` over `foo:bar` scripts
2354
- Docs: Use `docs/` folder, lowercase-with-hyphens.md filenames, pithy writing with visuals
2455
- Dependencies: After `package.json` edits, run `pnpm install` to update `pnpm-lock.yaml`
56+
- Backward Compatibility: NO backward compat - we're our only consumers, make clean breaks
57+
- Work Safeguards: MANDATORY commit + backup branch before bulk changes
58+
- Safe Deletion: Use `safeDelete()` from `@socketsecurity/lib/fs` (NEVER `fs.rm/rmSync` or `rm -rf`)
2559

2660
---
2761

@@ -83,11 +117,11 @@ TypeScript implementation of [Package URL specification](https://github.com/pack
83117
### Commands
84118
- **Build**: `pnpm build` (production build)
85119
- **Watch**: `pnpm build --watch` (dev mode with 68% faster incremental builds)
86-
- **Test**: `pnpm test`, `pnpm test:unit`
87-
- **Type check**: `pnpm check:tsc`
88-
- **Lint**: `pnpm check:lint`
120+
- **Test**: `pnpm test`
121+
- **Type check**: `pnpm type`
122+
- **Lint**: `pnpm lint`
89123
- **Check all**: `pnpm check`
90-
- **Fix**: `pnpm check:lint:fix` or `pnpm fix`
124+
- **Fix**: `pnpm fix`
91125
- **Coverage**: `pnpm cover`
92126

93127
**Development tip:** Use `pnpm build --watch` for 68% faster rebuilds (9ms vs 27ms). Incremental builds use esbuild's context API for in-memory caching.
@@ -208,30 +242,13 @@ With `exactOptionalPropertyTypes`, assign conditionally:
208242
- **Test helpers**: `test/utils/test-helpers.mts` - Reusable test utilities
209243
- **Assertion helpers**: `test/utils/assertions.mts` - Property validation helpers
210244

211-
#### Test Helpers (`test/utils/test-helpers.mts`)
245+
#### Test Helpers
212246

213-
**createTestPurl(type, name, opts?)** - Factory for creating PackageURL instances
214-
```typescript
215-
import { createTestPurl } from './utils/test-helpers.mts'
247+
Test helpers in `test/utils/test-helpers.mts`:
248+
- `createTestPurl(type, name, opts?)` - Factory for PackageURL instances
249+
- `createTestFunction(returnValue?)` - Creates test functions with optional return values
216250

217-
// Before: new PackageURL('npm', undefined, 'lodash', '4.17.21', undefined, undefined)
218-
// After:
219-
const purl = createTestPurl('npm', 'lodash', { version: '4.17.21' })
220-
221-
// With all options:
222-
const purl = createTestPurl('npm', 'lodash', {
223-
version: '4.17.21',
224-
namespace: '@scope',
225-
qualifiers: { arch: 'x64' },
226-
subpath: 'dist/index.js'
227-
})
228-
```
229-
230-
**createTestFunction(returnValue?)** - Creates test functions with optional return values
231-
```typescript
232-
const testFn = createTestFunction('result')
233-
expect(testFn()).toBe('result')
234-
```
251+
See file for usage examples.
235252

236253
#### Running Tests
237254
- **All tests**: `pnpm test` or `pnpm test:unit`

README.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,13 @@
22

33
[![Socket Badge](https://socket.dev/api/badge/npm/package/@socketregistry/packageurl-js)](https://socket.dev/npm/package/@socketregistry/packageurl-js)
44
[![CI - @socketregistry/packageurl-js](https://github.com/SocketDev/socket-packageurl-js/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-packageurl-js/actions/workflows/ci.yml)
5+
![Coverage](https://img.shields.io/badge/coverage-99.72%25-brightgreen)
56

67
[![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
78
[![Follow @socket.dev on Bluesky](https://img.shields.io/badge/[email protected]?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
89

9-
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).
10+
TypeScript Package URL (purl) parser and builder.
11+
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).
1012

1113
## What is a PURL?
1214

@@ -33,7 +35,7 @@ pkg:maven/org.springframework/[email protected]
3335

3436
**Supports 35+ ecosystems**: npm, pypi, maven, gem, cargo, nuget, composer, golang, docker, and more.
3537

36-
## Installation
38+
## Install
3739

3840
```sh
3941
pnpm install @socketregistry/packageurl-js
@@ -123,20 +125,16 @@ function processPurl(type: EcosystemString) {
123125
}
124126
```
125127

126-
## Documentation
127-
128-
| Doc | Description |
129-
|-----|-------------|
130-
| **[Getting Started](./docs/getting-started.md)** | Quick setup guide for contributors |
131-
| **[API Reference](./docs/api-reference.md)** | Complete API documentation |
132-
| **[Examples](./docs/usage-examples.md)** | Common use cases and patterns |
133-
| **[Builder Pattern](./docs/builder-pattern.md)** | Fluent builder guide |
134-
135128
## Development
136129

130+
**Quick commands:**
137131
```bash
138132
pnpm install # Install dependencies
139133
pnpm build # Build
140134
pnpm test # Test
141135
pnpm check # Lint + typecheck
142136
```
137+
138+
## License
139+
140+
MIT

0 commit comments

Comments
 (0)