perf: optimize CI and test performance

Improve test execution performance and CI throughput for socket-cli's
test suite (~48s, 2,819 tests):

CI Optimizations:
- Increase max-parallel from 4 to 8 for better job distribution
- Set test-timeout-minutes to 20 for subprocess-heavy tests
- Add commented sharded test job template for future use

Test Optimizations:
- Enable fileParallelism in vitest.config.mts for better thread utilization
- Format test includes for consistency

Documentation:
- Add Performance Optimization section with timing analysis
- Add CI/CD Optimization section with GitHub Actions best practices
- Update Build/Dist Structure to reference dedicated docs
- Update linting description (remove oxlint reference)
- Document test sharding strategy for future improvements

Author: jdalton

.github/workflows/ci.yml

@@ -47,6 +47,36 @@ jobs:
       node-versions: ${{ inputs.node-versions || '[20, 22, 24]' }}
       os-versions: '["ubuntu-latest", "macos-latest", "windows-latest"]'
       fail-fast: false
+      # Increase parallelization for socket-cli's longer test suite (~48s).
+      # Default is 4, we increase to 8 for better performance.
+      max-parallel: 8
+      # Increase timeout for slower subprocess-heavy tests.
+      test-timeout-minutes: 20
+
+  # Sharded unit tests (optional, enable for faster CI).
+  # To enable: uncomment this job and set `run-test: false` in the ci job above.
+  # test-sharded:
+  #   name: Unit Tests (Sharded ${{ matrix.shard }}/3)
+  #   runs-on: ${{ matrix.os }}
+  #   timeout-minutes: 15
+  #   strategy:
+  #     fail-fast: false
+  #     matrix:
+  #       node-version: ${{ fromJSON(inputs.node-versions || '[20, 22, 24]') }}
+  #       os: [ubuntu-latest, macos-latest, windows-latest]
+  #       shard: [1, 2, 3]
+  #   steps:
+  #     - uses: SocketDev/socket-registry/.github/actions/setup-and-install@51be85d39d3b4a42dd9d4712948b9d30a2e04794
+  #       with:
+  #         node-version: ${{ matrix.node-version }}
+  #
+  #     - name: Build CLI
+  #       working-directory: packages/cli
+  #       run: pnpm run build
+  #
+  #     - name: Run unit tests (shard ${{ matrix.shard }})
+  #       working-directory: packages/cli
+  #       run: pnpm test:unit --shard=${{ matrix.shard }}/3
 
   e2e:
     name: E2E Tests

CLAUDE.md

@@ -127,32 +127,16 @@ CLI tool for Socket.dev security analysis, built with TypeScript (.mts extension
 - TypeScript with tsgo or tsc
 - Individual file compilation
 - Multiple environment configs
-- Dual linting (oxlint + eslint), Biome formatting
+- ESLint linting, Biome formatting
 
 ### Build/Dist Structure
 
-**MANDATORY**: All packages follow build/dist pattern.
+**MANDATORY**: All packages follow build/dist pattern. See [docs/build/build-dist-structure.md](docs/build/build-dist-structure.md) for complete details.
 
-**Philosophy**:
+**Quick summary**:
 - **`build/`** (gitignored) = Workspace + historical builds archive
 - **`dist/`** (tracked) = Blessed canonical releases
 
-**Structure**:
-```
-packages/<package>/
-├── build/                    # Gitignored
-│   ├── tmp/                  # Current build intermediates
-│   ├── cache/                # Downloads, source clones
-│   └── archive/              # Historical builds
-│       ├── YYYY-MM-DD-NNN-description/
-│       └── latest/           # Symlink to most recent
-└── dist/                     # Tracked releases
-```
-
-**@socketbin Conventions**:
-- **Executables**: `packages/socketbin-cli-<platform>-<arch>/bin/socket` (tracked)
-- **Libraries**: `packages/socketbin-cli-ai/dist/` (WASM + JS, gitignored)
-
 ### Documentation Hierarchy
 
 **Tier 1**: `/docs/` - Monorepo-wide (architecture, build systems, guides)
@@ -165,6 +149,49 @@ packages/<package>/
 
 Uses Vitest with comprehensive test helpers.
 
+#### Performance Optimization
+
+**Test Execution Times** (measured):
+- Unit tests: ~48s (2,819 tests)
+- Bottleneck: `cmd-scan-reach.test.mts` (47s, 51 subprocess spawns)
+
+**Optimization Strategies**:
+1. **File-level parallelization**: Enabled in vitest.config.mts
+2. **CPU-based thread pool**: `maxThreads: os.cpus().length`
+3. **Test sharding**: Use `--shard` flag for CI distribution
+   ```bash
+   pnpm test:unit --shard=1/3  # Run 1st third
+   pnpm test:unit --shard=2/3  # Run 2nd third
+   pnpm test:unit --shard=3/3  # Run 3rd third
+   ```
+
+**Future Improvements**:
+- Split cmd-scan-reach.test.mts into logical groups (dry-run, validation, execution)
+- Implement process pool for CLI subprocess tests
+- Reduce per-test subprocess overhead
+
+#### CI/CD Optimization
+
+**GitHub Actions** (socket-cli-specific):
+- **max-parallel: 8** - Higher than default (4) for longer test suites
+- **test-timeout-minutes: 20** - Accommodates subprocess-heavy tests
+- **Matrix**: 3 Node versions × 3 OS platforms = 9 parallel jobs
+
+**Caching Best Practices**:
+1. **pnpm store**: Cached via `pnpm/action-setup` (automatic)
+2. **node_modules**: Implicitly cached via pnpm store
+3. **Build artifacts**: Consider caching `dist/` between test runs
+4. **Vitest cache**: `.vitest` directory (already gitignored)
+
+**Test Sharding** (future):
+```yaml
+strategy:
+  matrix:
+    shard: [1, 2, 3]
+steps:
+  - run: pnpm test:unit --shard=${{ matrix.shard }}/3
+```
+
 #### Test Helpers
 1. **CLI Execution** (`test/helpers/cli-execution.mts`)
    - `executeCliCommand()`, `expectCliSuccess()`, `expectCliError()`, `executeCliJson()`

packages/cli/vitest.config.mts

@@ -22,10 +22,7 @@ export default defineConfig({
   test: {
     globals: false,
     environment: 'node',
-    include: [
-      'test/**/*.test.{mts,ts}',
-      'src/**/*.test.{mts,ts}',
-    ],
+    include: ['test/**/*.test.{mts,ts}', 'src/**/*.test.{mts,ts}'],
     exclude: [
       '**/node_modules/**',
       '**/dist/**',
@@ -66,6 +63,9 @@ export default defineConfig({
     },
     testTimeout: 30_000,
     hookTimeout: 30_000,
+    // Enable file-level parallelization for better performance.
+    // Large test files (like cmd-scan-reach.test.mts) will run in separate threads.
+    fileParallelism: true,
     coverage: {
       provider: 'v8',
       reporter: ['text', 'json', 'html', 'lcov', 'clover'],