|
| 1 | +--- |
| 2 | +name: audit-js-dependencies |
| 3 | +description: Audit JavaScript and TypeScript dependencies across every directory in this repository that contains a package.json, using the correct install root for each project, apply non-breaking security upgrades, and stop to summarize any fixes that require a major-version change. Use when asked to run dependency audits, update vulnerable npm or yarn packages, reduce JavaScript dependency CVEs, or review whether vulnerable dependency fixes can be applied safely without breaking changes. |
| 4 | +--- |
| 5 | + |
| 6 | +# Audit JS Dependencies |
| 7 | + |
| 8 | +Use this skill to handle repo-wide JS dependency audits without double-auditing workspace members or blindly applying major upgrades. |
| 9 | + |
| 10 | +## Audit Scope |
| 11 | + |
| 12 | +Audit these install roots: |
| 13 | + |
| 14 | +- `.` for the npm workspace root and all workspace members under `packages/authgear-core`, `packages/authgear-web`, `packages/authgear-react-native`, and `packages/authgear-capacitor` |
| 15 | +- `example/reactweb` |
| 16 | +- `example/reactnative` |
| 17 | +- `example/capacitor` |
| 18 | +- `website` |
| 19 | + |
| 20 | +Do not run `npm audit` separately inside `packages/authgear-core`, `packages/authgear-web`, `packages/authgear-react-native`, or `packages/authgear-capacitor`. Those packages are installed and resolved by the repo root workspace and root `package-lock.json`. |
| 21 | + |
| 22 | +Use these package managers: |
| 23 | + |
| 24 | +- `.`: `npm` |
| 25 | +- `example/reactweb`: `npm` |
| 26 | +- `example/reactnative`: `yarn` |
| 27 | +- `example/capacitor`: `npm` |
| 28 | +- `website`: `npm` |
| 29 | + |
| 30 | +## Workflow |
| 31 | + |
| 32 | +1. Audit each install root with its existing package manager. |
| 33 | +2. Apply only fixes that stay within the current major line unless the user explicitly asks for breaking upgrades. |
| 34 | +3. Re-run audits after each change. |
| 35 | +4. Run lightweight verification for each touched project. |
| 36 | +5. If a fix requires a major bump, stop and report it instead of applying it. |
| 37 | + |
| 38 | +## Audit Commands |
| 39 | + |
| 40 | +Use these commands: |
| 41 | + |
| 42 | +```bash |
| 43 | +npm audit --json |
| 44 | +npm outdated --json |
| 45 | +``` |
| 46 | + |
| 47 | +```bash |
| 48 | +yarn audit --json |
| 49 | +yarn outdated --json |
| 50 | +``` |
| 51 | + |
| 52 | +If dependencies are missing, install them with the package manager already used by that directory before auditing. Keep lockfiles aligned with the existing manager. |
| 53 | + |
| 54 | +## Decide Whether A Fix Is Non-Breaking |
| 55 | + |
| 56 | +Treat a fix as non-breaking only when at least one of these is true: |
| 57 | + |
| 58 | +- `npm audit fix` or the package-manager equivalent resolves the issue without changing declared major versions |
| 59 | +- The minimal fixed version stays in the same major line as the current declared dependency |
| 60 | +- The package is transitive and can be fixed by a lockfile update or override/resolution that does not widen a package to a new major |
| 61 | + |
| 62 | +Use registry metadata to verify the target version before changing manifests: |
| 63 | + |
| 64 | +```bash |
| 65 | +npm view <package> version versions --json |
| 66 | +``` |
| 67 | + |
| 68 | +Check the current declared range in `package.json`, the vulnerable installed version from the audit report, and the minimum patched version. If the patched version requires a new major, do not apply it automatically. |
| 69 | + |
| 70 | +Before adding any `overrides` or `resolutions`, check whether the existing declared range already allows a patched version. If it does, prefer a lockfile-only update via `npm audit fix`, the package-manager equivalent, or a non-breaking reinstall over changing `package.json`. |
| 71 | + |
| 72 | +When an override or resolution is genuinely required, keep its scope as narrow as possible: |
| 73 | + |
| 74 | +- For npm, use `npm explain <package>` to identify the exact parent chain and scope the override to the nested dependency path instead of the package globally. |
| 75 | +- For Yarn, use `yarn why <package>` and prefer the most specific resolution pattern that matches the vulnerable path. |
| 76 | +- If the vulnerable package can be updated through the existing semver range after a lockfile refresh, remove the temporary override or resolution instead of leaving it behind. |
| 77 | +- As part of the final pass, review any existing or newly added `overrides` and `resolutions` touched by the audit and remove entries that are now outdated, redundant, or no longer needed. |
| 78 | +- If an override or resolution crosses a major version line for a transitive dependency, only do it when you have primary-source evidence that the major change is compatible in this context, and note that evidence alongside the manifest change before verification. |
| 79 | + |
| 80 | +For this repo, also account for these specifics: |
| 81 | + |
| 82 | +- Keep local file references such as `../../packages/authgear-web` and `../../packages/authgear-react-native` untouched |
| 83 | +- Preserve root `overrides` or per-project `resolutions` unless the fix requires adjusting them |
| 84 | +- In `example/reactnative`, use the existing `yarnauditfix` script only when it cleanly resolves lockfile-level vulnerabilities without introducing a major bump |
| 85 | + |
| 86 | +## Apply Safe Fixes |
| 87 | + |
| 88 | +Prefer the smallest change that clears the audit: |
| 89 | + |
| 90 | +1. Run `npm audit fix` in npm projects when it does not propose breaking upgrades. |
| 91 | +2. Re-check whether the vulnerability is already fixed by the refreshed lockfile before editing manifests. |
| 92 | +3. If a targeted package still needs a patch, install the minimal fixed version explicitly. |
| 93 | +4. Only add a narrowly scoped override or resolution when the existing declared range cannot otherwise land on the patched version. |
| 94 | +5. Update the lockfile with the same package manager that owns the directory. |
| 95 | +6. Re-run the audit immediately after each root is updated. |
| 96 | + |
| 97 | +When explicit targeted updates are needed, use commands in this shape: |
| 98 | + |
| 99 | +```bash |
| 100 | +npm install <package>@<fixed-version> |
| 101 | +``` |
| 102 | + |
| 103 | +```bash |
| 104 | +yarn add <package>@<fixed-version> |
| 105 | +``` |
| 106 | + |
| 107 | +Avoid opportunistic upgrades. The goal is to remove vulnerable dependencies with the narrowest safe diff. |
| 108 | + |
| 109 | +## Verify After Changes |
| 110 | + |
| 111 | +Re-run the audit for every root you touched. Then run the most relevant lightweight verification for each affected project: |
| 112 | + |
| 113 | +- Repo root: `npm test` and `npm run typecheck` |
| 114 | +- `example/reactweb`: `npm run build` |
| 115 | +- `example/reactnative`: `npm test` and `npm run typecheck` |
| 116 | +- `example/capacitor`: `npm run build` |
| 117 | +- `website`: `npm run build` |
| 118 | + |
| 119 | +If a dependency update affects native mobile tooling, note any heavier validation you did not run, such as Capacitor or React Native platform builds. |
| 120 | + |
| 121 | +## Report Breaking Changes Instead Of Applying Them |
| 122 | + |
| 123 | +If the audit can only be fixed through a major-version change, stop and notify the user with a concise summary: |
| 124 | + |
| 125 | +- Affected project root |
| 126 | +- Package name |
| 127 | +- Current declared range |
| 128 | +- Minimum fixed version |
| 129 | +- Why it is breaking |
| 130 | +- Whether a lockfile-only mitigation or override was available |
| 131 | +- The verification work that would be needed after a major upgrade |
0 commit comments