JavaScript Dependency Modernization

Use when modernizing JavaScript dependency graphs. Modernize npm dependency graphs without hiding warnings, forcing unproven transitive APIs, or weakening runtime and packaging behavior.

When to use

• npm install or npm ci reports deprecated or unsupported packages.
• A direct package is maintained but pulls obsolete transitive dependencies.
• Build-only tooling carries optional legacy targets.
• A repository needs an enforceable supported-dependency policy.
• A library replacement must preserve file formats, streams, native modules, or packaged desktop targets.

Operating contract

1. Clarify whether the requirement prohibits all deprecations, only unsupported modules, or both. These are different acceptance criteria.
2. Diagnose every warning through its direct parent chain before editing.
3. Prefer maintained replacements and supported releases over suppression, prereleases, audit fix --force, or speculative overrides.
4. Preserve the observable contract with focused regressions before changing dependencies.
5. Verify the physical install and packaged artifact, not merely manifest text or lockfile resolution.
6. Make policy checks fail closed and prove them with adversarial RED→GREEN fixtures.
7. Keep platform-native packaging gates explicit and bind review evidence to the final exact head.

Workflow

1. Inventory and ancestry

Record the exact warning package/version pairs, then use:

• npm explain <package>
• npm ls --all
• direct manifest inspection
• package-lock.json package records and deprecated fields
• registry/release metadata for candidate replacements

Classify each warning as direct, transitive runtime, build-only, optional, or peer-only. Do not infer safety from package names alone.

2. Bound behavior before replacement

Map imports, callers, serialization/streaming behavior, error propagation, generated formats, native ABI transitions, and package targets. Add focused tests for the behavior the old dependency currently supplies.

For desktop builders, list every configured target and determine whether an obsolete peer is loaded globally or lazily only for an unused target. Removing or omitting a peer is valid only when the unused target is prohibited by policy.

3. Choose the migration

Preference order:

1. Stable supported upgrade.
2. Maintained API-compatible replacement.
3. Small adapter over a maintained replacement.
4. Exact supported transitive override only when caller API compatibility and retained target packaging are proven.
5. Explicitly blocked migration when no supported path preserves the required contract.

Do not call warning suppression a fix. Do not use an alpha release merely to reduce warning count. Do not move an unsupported tool to another package or lockfile and claim removal.

4. Enforce the result

A repository policy should independently validate:

• direct dependency support constraints;
• lockfile structure and versions;
• the physical node_modules inventory;
• required exact compatibility overrides;
• prohibited legacy targets and required supported targets;
• intentionally absent peer-only metadata;
• packaged runtime exclusion where applicable.

The policy is security-sensitive code. Treat package paths, manifests, lock records, symlinks, malformed metadata, and version syntax as untrusted inputs. See references/fail-closed-npm-policy.md.

5. Verify after the latest mutation

Run, as applicable:

• clean npm ci with captured warning count;
• the dependency policy against that clean install;
• targeted npm ls and independent physical inventory;
• focused behavior regressions;
• full tests, typecheck, lint, build, and audit policy;
• each retained package target on its native OS;
• packaged artifact inspection for resources and forbidden modules;
• native-module ABI restoration followed by focused tests when packaging rebuilds native dependencies.

An overall shell exit from semicolon-separated commands proves only the last command. Use fail-fast chaining or capture every status separately.

Review and orchestration

• Put broad dependency migration work on a fresh branch; do not mutate an already-approved security PR head.
• An empty reviewer report or interrupted reviewer is no verdict. Preserve the immutable candidate and use a bounded retry path.
• Any new commit invalidates older exact-head approvals.
• Before direct remediation edits, check whether a durable supervisor has launched a mutation owner for the same worktree. Generated coordination artifacts and a child process can appear between callbacks; stop editing on overlap and preserve the live diff.
• Post explicit exact-head review verdicts where repository users can audit them, then read the comment back.
• Native packaging gates can remain external, but code-level policy failures cannot be waived implicitly by successful application tests.

Completion checklist

• Requirement distinguishes deprecated from unsupported modules.
• Every warning is mapped to its parent chain.
• Replacement or omission rationale is source-backed.
• Behavior regressions cover serialization, streams, errors, and security invariants.
• Clean install warning count meets the stated policy.
• No prohibited package is physically installed.
• Lockfile and physical inventory fail closed on malformed state.
• CI runs the policy after a clean install.
• All retained native package targets are validated or explicitly remain gated.
• Packaged runtime excludes prohibited modules and retains required resources.
• Exact-head reviewer and final-verifier artifacts match the current head.

---

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/javascript-dependency-modernization/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/javascript-dependency-modernization/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.