---
name: xylabs-xy-deplint-fix
description: >
  Fix dependency declaration errors in one or more packages using `xy deplint --fix`.
  Use this skill whenever the user asks to fix deplint errors, clean up package.json
  dependencies, or resolve "dependency should be devDependency" / "missing dependency"
  warnings in an XY Labs monorepo. If a package name is supplied as an argument, fix
  only that package. If no argument is given, fix all packages in the repo.
---

# xylabs-xy-deplint-fix

Diagnoses and fixes `package.json` dependency declaration errors reported by `xy deplint`
in an XY Labs monorepo. The `--fix` flag handles all error types automatically.

---

## Package Manager Detection

Check the repo root before running any command:

* `yarn.lock` present → prefix commands with **yarn** (e.g. `yarn xy deplint`)
* `pnpm-lock.yaml` present → prefix commands with **pnpm**

All commands below are shown without a prefix. Prepend accordingly.

---

## What `--fix` handles

| Error message | Fix applied |
|---|---|
| `dependency should be devDependency` | Moves from `dependencies` → `devDependencies` |
| `Unused dependency` | Removes from `dependencies` |
| `Unused devDependency` | Removes from `devDependencies` |
| `Unused peerDependency` | Removes from `peerDependencies` |
| `Missing dependency` | Adds to `dependencies` (version from node_modules) |
| `Missing devDependency` | Adds to `devDependencies` (version from node_modules) |
| `Unsatisfied peer dependency` | Adds to appropriate section based on context |

Empty dependency sections are removed automatically. All edits are sorted with
`sort-package-json`.

---

## Workflow

### Step 1 — Fix

```bash
# Whole repo
xy deplint --fix

# Single package
xy deplint --fix package-name
```

This scans for problems and applies fixes to `package.json` files in place.
Review the output to see what was changed.

### Step 2 — Install

After `--fix` modifies `package.json` files, reinstall from the repo root so the
lockfile and `node_modules` reflect the changes:

```bash
yarn install   # or: pnpm install
```

Do **not** use `yarn workspaces focus` — it strips the root-level `xy` script bindings.

### Step 3 — Verify

Re-run deplint without `--fix` to confirm all issues are resolved:

```bash
xy deplint [package-name]
```

**Definition of done:**

```text
Deplint: Found no dependency problems. ✔
```

If problems remain, repeat from Step 1. Some issues (e.g. newly-added deps introducing
their own unsatisfied peers) may require multiple passes.

---

## Edge Cases

### Multiple passes required

Fixing missing dependencies may introduce new unsatisfied peer dependency errors, since
the newly-added package has its own peers. Run the fix → install → verify loop until
clean.

### Version resolution for missing deps

`--fix` resolves versions by reading the installed version from `node_modules` and
prefixing with `~`. If the package is not installed, it falls back to `*`. After
installing and re-running, the version will be resolved correctly on the next pass.

### Aggregator packages

Aggregator packages (no `src/`, only re-export workspace children) may need all workspace
children as `devDependencies`. `--fix` handles this — it moves deps to devDependencies
and adds missing transitive deps automatically.

### `dependency should be devDependency` for a runtime import

deplint may flag a dep as "should be devDependency" even when it is imported for a
runtime value. This happens when the dep is a foundational library that consumers are
expected to already have installed (behaves like a peer). `--fix` moves it to
`devDependencies`. If the dep must be guaranteed for external npm consumers, manually
add it to `peerDependencies` after fixing.

### `yarn workspaces focus` breaks the `xy` command

`yarn workspaces focus <package>` installs only the deps for that one package and removes
the root-level `xy` script bindings. Always use `yarn install` (full) after fixing.
