# Renovate 의존성 범프 후 npm workspaces 모노레포에서 qs 모듈 해석 문제 수정 ## 문제 Renovate가 `qs`를 범프한 뒤 npm workspaces 모노레포에서 모듈 해석이 깨졌습니다. 일반적인 증상은 다음과 같습니다: - `Cannot find module 'qs'` 또는 `ERR_MODULE_NOT_FOUND` - 워크스페이스 중 하나만 실패하고 나머지는 정상 동작 - 로컬에서는 통과하지만 CI에서 실패 - `npm ls qs`가 중복되거나 유효하지 않은(extraneous) 항목을 표시 ## 원인 npm workspaces는 의존성을 루트 `node_modules`로 호이스팅합니다. Renovate가 `qs`를 범프할 때 다음과 같은 상황이 발생할 수 있습니다: 1. **버전 불일치**: 서로 다른 워크스페이스가 서로 다른 `qs` 버전을 요구하게 되어, 하나는 루트로 호이스팅되고 다른 하나는 워크스페이스 로컬 `node_modules`에 중첩됩니다. 2. **오래된 lockfile**: `package-lock.json`이 부분적으로만 갱신되어 해석 트리가 실제 `package.json`과 어긋납니다. 3. **중첩된 `node_modules`**: 이전 설치에서 남은 워크스페이스 로컬 `node_modules/qs`가 루트 호이스팅된 버전을 가립니다. 4. **peer/transitive 불일치**: `qs`에 의존하는 패키지(예: `express`, `body-parser`)가 범프된 버전과 호환되지 않는 버전을 고정하고 있을 수 있습니다. ## 해결 방법 ### 1. 현재 상태 진단 ```bash npm ls qs --all ``` 중복, `invalid`, `extraneous` 항목을 확인합니다. 어떤 워크스페이스가 어떤 버전을 해석하는지 파악합니다. ### 2. 클린 재설치 ```bash # 워크스페이스 로컬 node_modules 포함해 모두 제거 rm -rf node_modules package-lock.json find . -name node_modules -type d -prune -exec rm -rf {} + npm install ``` 이렇게 하면 lockfile이 `package.json`과 일치하게 다시 생성되고, 남아 있던 중첩 `qs`가 제거됩니다. ### 3. 버전 정렬 루트 `package.json`에 `overrides`를 추가해 `qs` 버전을 하나로 고정합니다: ```json { "overrides": { "qs": "^6.13.0" } } ``` 그런 다음 다시 설치합니다: ```bash npm install npm ls qs --all ``` 이제 모든 워크스페이스가 동일한 호이스팅된 `qs`를 해석해야 합니다. ### 4. Renovate 설정 조정 재발을 막기 위해 Renovate가 `qs`를 범프할 때 lockfile을 완전히 갱신하도록 설정합니다: ```json { "lockFileMaintenance": { "enabled": true, "schedule": ["before 5am on monday"] }, "packageRules": [ { "matchPackageNames": ["qs"], "groupName": "qs", "rangeStrategy": "replace" } ] } ``` `rangeStrategy: "replace"`는 범프 시 `package.json`의 범위를 갱신해 lockfile과의 불일치를 줄입니다. ### 5. CI 검증 CI에서 클린 설치와 해석 검사를 수행합니다: ```bash npm ci npm ls qs --all ``` `npm ls`가 0이 아닌 종료 코드를 반환하면 빌드가 실패하도록 하여, 해석 문제가 조용히 지나가지 않게 합니다. ## 확인 ```bash npm ls qs --all ``` 출력에 단일 해석된 버전이 표시되고 `invalid`/`extraneous` 항목이 없어야 합니다. 그런 다음 실패했던 워크스페이스에서 테스트를 실행해 모듈이 정상적으로 해석되는지 확인합니다.

I can't actually run commands or inspect your repo from here, so I'll give you the exact steps and the reasoning to apply. Follow them in order.

## 1. Locate where `qs` is used

Search the monorepo for direct and transitive usage:

```bash
# direct imports
rg -n "from ['\"]qs['\"]|require\(['\"]qs['\"]\)" --glob '!node_modules'

# transitive via co-body / @web/test-runner-core
rg -n "co-body|@web/test-runner-core" --glob '!node_modules'
npm ls qs --all
```

Typical culprits in a workspaces monorepo:

- A test helper that spins up a dev server using `co-body` (which depends on `qs`).
- `@web/test-runner-core` pulling `qs` transitively for its server middleware.
- A `package.json` in the library workspace that imports `qs` in a test file but never declares it.

## 2. Determine why it stopped resolving

Check these in order:

```bash
# Is qs present at the hoisted root?
ls node_modules/qs/package.json && node -p "require('./node_modules/qs/package.json').version"

# Is it nested under the library workspace?
ls packages/<library>/node_modules/qs 2>/dev/null

# What does the lockfile say?
node -e "const l=require('./package-lock.json'); for (const k of Object.keys(l.packages)) if (k.endsWith('node_modules/qs')) console.log(k, l.packages[k].version)"
```

The three failure modes to distinguish:

- **Hoisting gap**: `qs` is only declared as a transitive dep of `co-body`/`@web/test-runner-core`. After the bump, npm's hoisting placed it under a nested `node_modules` (or not at all) because the version range no longer satisfies the hoisted slot. The library workspace's test file imports `qs` directly, so it fails.
- **Lockfile drift**: `package-lock.json` still pins `node_modules/qs` at the old version, or has a stale entry that doesn't match the new `^6.17.0` range, so `npm ci` installs a tree where `qs` isn't resolvable from the library workspace.
- **Wrong package.json**: `qs` is imported in the library workspace's tests but declared in the root `package.json` (or another workspace), which works under hoisting by accident and breaks when the tree changes.

## 3. Fix (smallest change that works)

### a. Add `qs` to the library workspace `devDependencies`

In `packages/<library>/package.json`:

```json
"devDependencies": {
  "qs": "^6.17.0"
}
```

This makes the direct import legitimate and pins the range the tests actually need.

### b. Align the root `overrides.qs`

In the root `package.json`:

```json
"overrides": {
  "qs": "^6.17.0"
}
```

If the override was previously `^6.16.x` or absent, this forces every transitive `qs` (from `co-body`, `@web/test-runner-core`, etc.) to the bumped range so hoisting has a single consistent version to place at `node_modules/qs`.

### c. Correct `package-lock.json`

Regenerate from the repo root so the lockfile reflects both changes:

```bash
npm install
```

Then verify:

```bash
node -e "const l=require('./package-lock.json'); for (const k of Object.keys(l.packages)) if (k.endsWith('node_modules/qs')) console.log(k, l.packages[k].version)"
# expect: node_modules/qs 6.17.x
npm ls qs --all
```

Confirm `node_modules/qs` resolves at `6.17.x` and that no nested `qs` remains under the library workspace unless a genuinely incompatible range requires it.

### d. Verify CI locally

```bash
npm ci
npm test --workspace packages/<library>
```

Do not touch test files, do not add `skip`, do not widen ranges beyond `^6.17.0`.

## 4. Commit messages

Use conventional commits, no `feat:` or breaking markers, no em or en dashes.

```
chore(deps): add qs to library workspace devDependencies

The library tests import qs directly through the co-body and
@web/test-runner-core dev server path. Declaring it explicitly keeps
resolution stable when the hoisted tree changes.
```

```
chore(deps): align root overrides.qs with the bumped range

Forces transitive qs from co-body and @web/test-runner-core onto the
same version so npm hoists a single copy at node_modules/qs.
```

```
chore(deps): refresh package-lock.json for qs 6.17.0

Regenerated from the repo root so node_modules/qs resolves at the
bumped version and npm ci produces a tree the library tests can use.
```

If you prefer a single commit, combine them:

```
chore(deps): fix qs resolution in library workspace after bump

Add qs to the library workspace devDependencies, align the root
overrides.qs range, and refresh package-lock.json so node_modules/qs
resolves at 6.17.0. The library tests import qs through the co-body
and @web/test-runner-core dev server path, and the previous tree only
resolved it by accident of hoisting.
```

## 5. Sanity checks before pushing

- `git diff` shows only: library `package.json` (one line), root `package.json` (override line), `package-lock.json`.
- No test files changed.
- `npm ci && npm test --workspace packages/<library>` passes.
- `npm ls qs --all` shows a single hoisted `6.17.x` (or nested copies only where a range genuinely requires it).
- Commit message has no `feat:`, no `!`, no em or en dashes.

If after step 2 you find `qs` was declared in the wrong `package.json` (for example root instead of the library workspace), remove it from the wrong location as part of the same change so the declaration matches the import site.