You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Always build before testing**: Run `pnpm run build:dist:src` before running tests to ensure dist files are up to date
71
+
-**Test single file**: ✅ CORRECT: `pnpm run test:unit src/commands/specific/cmd-file.test.mts`
72
+
- ❌ WRONG: `pnpm run test:unit -- src/commands/specific/cmd-file.test.mts` (runs ALL tests!)
73
+
-**Test multiple files**: ✅ CORRECT: `pnpm run test:unit file1.test.mts file2.test.mts`
74
+
-**Test with pattern**: ✅ CORRECT: `pnpm run test:unit src/commands/specific/cmd-file.test.mts -t "pattern"`
75
+
- ❌ WRONG: `pnpm run test:unit -- src/commands/specific/cmd-file.test.mts -t "pattern"`
72
76
-**Update snapshots**:
73
-
- All tests: `pnpm testu` (builds first, then updates all snapshots)
74
-
- Single file: ✅ CORRECT: `pnpm testu src/commands/specific/cmd-file.test.mts`
75
-
- ❌ WRONG: `pnpm testu -- src/commands/specific/cmd-file.test.mts` (updates ALL snapshots!)
76
-
-**Update with --update flag**: `pnpm test:unit src/commands/specific/cmd-file.test.mts --update`
77
+
- All tests: `pnpm run testu` (builds first, then updates all snapshots)
78
+
- Single file: ✅ CORRECT: `pnpm run testu src/commands/specific/cmd-file.test.mts`
79
+
- ❌ WRONG: `pnpm run testu -- src/commands/specific/cmd-file.test.mts` (updates ALL snapshots!)
80
+
-**Update with --update flag**: `pnpm run test:unit src/commands/specific/cmd-file.test.mts --update`
77
81
-**Timeout for long tests**: Use `timeout` command or specify in test file
78
82
79
83
#### Vitest Memory Optimization (CRITICAL)
80
84
-**Pool configuration**: Use `pool: 'forks'` with `singleFork: true`, `maxForks: 1`, `isolate: true`
81
85
-**Memory limits**: Set `NODE_OPTIONS="--max-old-space-size=4096 --max-semi-space-size=512"` in `.env.test`
82
86
-**Timeout settings**: Use `testTimeout: 60000, hookTimeout: 60000` for stability
83
87
-**Thread limits**: Use `singleThread: true, maxThreads: 1` to prevent RegExp compiler exhaustion
84
-
-**Test cleanup**: 🚨 MANDATORY - Import and use `trash` package: `import { trash } from 'trash'` then `await trash([paths])`
88
+
-**Test cleanup**: 🚨 MANDATORY - Use `await trash([paths])` in test scripts/utilities only. For cleanup within `/src/` test files, use `fs.rm()` with proper error handling
85
89
86
90
### Git Commit Guidelines
87
91
-**🚨 FORBIDDEN**: NEVER add Claude co-authorship or Claude signatures to commits
88
92
-**🚨 FORBIDDEN**: Do NOT include "Generated with Claude Code" or similar AI attribution in commit messages
89
93
-**Commit messages**: Should be written as if by a human developer, focusing on the what and why of changes
90
94
-**Professional commits**: Write clear, concise commit messages that describe the actual changes made
95
+
-**Pithy messages**: Keep commit messages concise and to the point - avoid lengthy explanations
91
96
92
97
### Running the CLI locally
93
-
-**Build and run**: `npm run build && npm exec socket` or `pnpm build && pnpm exec socket`
94
-
-**Quick build + run**: `npm run bs` or `pnpm bs` (builds source only, then runs socket)
95
-
-**Run without build**: `npm run s` or `pnpm s` (runs socket directly)
98
+
-**Build and run**: `pnpm run build && pnpm exec socket`
99
+
-**Quick build + run**: `pnpm run bs` (builds source only, then runs socket)
100
+
-**Run without build**: `pnpm run s` (runs socket directly)
96
101
-**Native TypeScript**: `./sd` (runs the CLI without building using Node.js native TypeScript support on Node 22+)
97
102
98
103
### Package Management
@@ -101,6 +106,9 @@ You are a **Principal Software Engineer** responsible for:
-**Add dev dependency**: `pnpm add -D <package> --save-exact`
103
108
-**Update dependencies**: `pnpm update`
109
+
-**Script execution**: Always use `pnpm run <script>` for package.json scripts to distinguish from built-in pnpm commands
110
+
- ✅ CORRECT: `pnpm run build`, `pnpm run test`, `pnpm run check`
111
+
- ❌ AVOID: `pnpm build`, `pnpm test` (unclear if built-in or script)
104
112
-**🚨 MANDATORY**: Always add dependencies with exact versions using `--save-exact` flag to ensure reproducible builds
105
113
-**Dependency validation**: All dependencies MUST be pinned to exact versions without range specifiers like `^` or `~`
106
114
-**Override behavior**: pnpm.overrides in package.json controls dependency versions across the entire project
@@ -148,6 +156,38 @@ Each command follows a consistent pattern:
148
156
- Fixtures in `test/fixtures/`
149
157
- Coverage reporting available
150
158
159
+
#### Test Organization Best Practices
160
+
-**Modular test files**: Split large test files by functionality (e.g., `main.test.mts` → `socket-sdk-basic.test.mts`, `socket-sdk-organization.test.mts`, etc.)
161
+
-**Test file naming**: Use descriptive names that reflect the module being tested
162
+
-**Test directory structure**: 🚨 MANDATORY - Standardize test directory organization across all Socket projects:
- ❌ FORBIDDEN: Placing @fileoverview after imports or other code
244
292
-**Import order**: Node.js built-ins first, then third-party packages, then local imports
245
293
-**Import grouping**: Group imports by source (Node.js, external packages, local modules)
294
+
-**Node.js module imports**: 🚨 MANDATORY - Always use `node:` prefix for Node.js built-in modules
295
+
- ✅ CORRECT: `import { readFile } from 'node:fs'`, `import path from 'node:path'`
296
+
- ❌ FORBIDDEN: `import { readFile } from 'fs'`, `import path from 'path'`
246
297
-**Type imports**: 🚨 ALWAYS use separate `import type` statements for TypeScript types, NEVER mix runtime imports with type imports in the same statement
247
298
- ✅ CORRECT: `import { readPackageJson } from '@socketsecurity/registry/lib/packages'` followed by `import type { PackageJson } from '@socketsecurity/registry/lib/packages'`
248
299
- ❌ FORBIDDEN: `import { readPackageJson, type PackageJson } from '@socketsecurity/registry/lib/packages'`
@@ -261,11 +312,14 @@ Socket CLI integrates with various third-party tools and services:
261
312
-**Dynamic imports**: 🚨 FORBIDDEN - Never use dynamic imports (`await import()`). Always use static imports at the top of the file
262
313
-**Sorting**: 🚨 MANDATORY - Always sort lists, exports, and items in documentation headers alphabetically/alphanumerically for consistency
263
314
-**Comment formatting**: 🚨 MANDATORY - ALL comments MUST follow these rules:
315
+
-**Single-line preference**: Prefer single-line comments (`//`) over multiline comments (`/* */`) unless for method headers, module headers, or copyright notices. Use single-line comments for property descriptions, inline explanations, and general code comments.
264
316
-**Periods required**: Every comment MUST end with a period, except ESLint disable comments and URLs which are directives/references. This includes single-line, multi-line, inline, and c8 ignore comments.
265
317
-**Sentence structure**: Comments should be complete sentences with proper capitalization and grammar.
266
318
-**Placement**: Place comments on their own line above the code they describe, not trailing to the right of code.
267
319
-**Style**: Use fewer hyphens/dashes and prefer commas, colons, or semicolons for better readability.
- ✅ CORRECT: `// This function validates user input.`
270
324
- ✅ CORRECT: `/* This is a multi-line comment that explains the complex logic below. */`
271
325
- ✅ CORRECT: `// eslint-disable-next-line no-await-in-loop` (directive, no period)
@@ -274,6 +328,7 @@ Socket CLI integrates with various third-party tools and services:
274
328
- ❌ WRONG: `// this validates input` (no period, not capitalized)
275
329
- ❌ WRONG: `const x = 5 // some value` (trailing comment)
276
330
-**Await in loops**: When using `await` inside for-loops, add `// eslint-disable-next-line no-await-in-loop` to suppress the ESLint warning when sequential processing is intentional
331
+
-**For...of loop type annotations**: 🚨 FORBIDDEN - Never use type annotations in for...of loop variable declarations. TypeScript cannot parse `for await (const chunk: Buffer of stream)` - use `for await (const chunk of stream)` instead and let TypeScript infer the type
277
332
-**If statement returns**: Never use single-line return if statements; always use proper block syntax with braces
278
333
-**List formatting**: Use `-` for bullet points in text output, not `•` or other Unicode characters, for better terminal compatibility
279
334
-**Existence checks**: Perform simple existence checks first before complex operations
@@ -287,6 +342,51 @@ Socket CLI integrates with various third-party tools and services:
287
342
-**Node.js fs imports**: 🚨 MANDATORY pattern - `import { someSyncThing, promises as fs } from 'node:fs'`
288
343
-**Process spawning**: 🚨 FORBIDDEN to use Node.js built-in `child_process.spawn` - MUST use `spawn` from `@socketsecurity/registry/lib/spawn`
289
344
-**Number formatting**: 🚨 REQUIRED - Use underscore separators (e.g., `20_000`) for large numeric literals. 🚨 FORBIDDEN - Do NOT modify number values inside strings
345
+
-**JSDoc function documentation**: 🚨 MANDATORY - Function JSDoc comments MUST follow this exact pattern:
346
+
-**Format**: Description only, with optional `@throws` - NO `@param` or `@returns` tags
347
+
-**Order**: Description paragraph, then `@throws` tag (if needed)
348
+
-**Closure**: End with `*/` immediately after the last JSDoc tag
349
+
-**Examples**:
350
+
- ✅ CORRECT:
351
+
```javascript
352
+
/**
353
+
* Check if a string contains a trusted domain using proper URL parsing.
354
+
*/
355
+
```
356
+
- ✅ CORRECT (with throws):
357
+
```javascript
358
+
/**
359
+
* Parse a configuration file and validate its contents.
360
+
* @throws {Error} When file cannot be read or parsed.
361
+
*/
362
+
```
363
+
- ❌ FORBIDDEN: Adding `@param` or `@returns` tags
364
+
- ❌ FORBIDDEN: Adding extra tags like `@author`, `@since`, `@example`, etc.
365
+
- ❌ FORBIDDEN: Adding empty lines between JSDoc tags
366
+
- ❌ FORBIDDEN: Adding extra content after the last JSDoc tag
367
+
368
+
### 🏗️ Function Options Pattern (MANDATORY)
369
+
-**🚨 REQUIRED**:ALL functions accepting options MUST follow this exact pattern:
- **Input validation errors**: Use `InputError` from `src/utils/errors.mts` for user input validation failures (missing files, invalid arguments, etc.)
@@ -357,3 +457,29 @@ Socket CLI integrates with various third-party tools and services:
357
457
- All patterns MUST follow established codebase conventions
358
458
-Error handling MUST be robust and user-friendly
359
459
-Performance considerations MUST be evaluated for any changes
460
+
461
+
## 📋 Recurring Patterns & Instructions
462
+
463
+
These are patterns and instructions that should be consistently applied across all Socket projects:
464
+
465
+
### 🏗️ Mandatory Code Patterns
466
+
1.**Options Parameter Pattern**: Use `{ __proto__: null, ...options } as SomeOptions`for all functions accepting options
467
+
2.**Reflect.apply Pattern**: Use `const { apply: ReflectApply } = Reflect` and `ReflectApply(fn, thisArg, [])` instead of`.call()`for method invocation
468
+
3.**Object Mappings**: Use `{ __proto__: null, ...mapping }`forstatic string-to-string mappings to prevent prototype pollution
469
+
4.**Import Separation**:ALWAYS separate type imports (`import type`) from runtime imports
470
+
5.**Node.js Imports**:ALWAYS use `node:` prefix forNode.js built-in modules
471
+
6.**🚨 TSGOPRESERVATION**:NEVER replace tsgo with tsc - tsgo provides enhanced performance and should be maintained across all Socket projects
472
+
473
+
### 🧪 Test Patterns & Cleanup
474
+
1.**Remove Duplicate Tests**: Eliminate tests that verify the same functionality across multiple files
475
+
2.**Centralize Test Data**: Use shared test fixtures instead of hardcoded values repeated across projects
476
+
3.**Focus Test Scope**: Each project should test its specific functionality, not dependencies' core features
477
+
478
+
### 🔄 Cross-Project Consistency
479
+
These patterns should be enforced across all Socket repositories:
480
+
- `socket-cli`
481
+
- `socket-packageurl-js`
482
+
- `socket-registry`
483
+
- `socket-sdk-js`
484
+
485
+
When working in any Socket repository, check CLAUDE.md files in other Socket projects for consistency and apply these patterns universally.
0 commit comments