Engineering Practice
Update a Dependency with a Reviewable Diff and a Recovery Plan
An executed disposable npm example upgrades strip-ansi from 6.0.1 to 7.1.2 and changes indirect ansi-regex from 5.0.1 to 6.4.0, exposing a CommonJS adapter failure. Complete diffs, fixed expected-output tests, an unsuccessful manifest-only restore, and a passing paired recovery form a bounded review pack.
Update a dependency by reviewing the resolved dependency changes, exercising the application boundary that uses the package, and retaining a recovery path before approving the candidate. A successful install does not prove that the caller still works. A manifest edit can also change indirect packages, so the review must include the lockfile rather than just the requested version number.
This LandOffer.ai guide uses an actual disposable npm fixture with synthetic strings to build a review pack and reproduce recovery after a failed update. The pinned historical versions are teaching inputs, not recommendations for the latest or safest release. No LandOffer or website dependencies, customer systems, pull requests, accounts, deployments, or production data were changed.

Define the update boundary and the reason to inspect it
The fixture represents a small plain-text build-transcript exporter. Its CommonJS adapter calls strip-ansi to remove ANSI styling from a string. The checks exercise this adapter’s text-output boundary only; they do not establish a complete log-sanitization or security system.
The baseline pins strip-ansi at 6.0.1. The candidate pins 7.1.2, crossing the package’s ESM transition. The purpose is to demonstrate a reviewable breaking-boundary update and its recovery, not to claim that this upgrade is necessary for a real service or that the baseline is suitable for continued production use.
The actual runtime is Node v26.9.0 with npm 11.19.1 on macOS arm64. When reproducing a dependency problem, record the environment alongside the failure: module interoperability, package-manager behavior, operating system, and installation options can affect the result. Do not replace the observed error with one you remember from an older Node release.
Upstream’s 7.0.0 release notes identify the move to pure ESM and a Node version requirement. The 7.1.2 release notes also discuss a vulnerability in 7.1.1. That is release-history evidence, not a security assessment of every package resolved in this fixture. Version 7.1.1 is not installed here, and no vulnerability scan is claimed.
Before updating a real component, write down the motivation, intended version, affected consumers, runtime constraints, and expected rollback boundary. Keep unrelated package churn out of the same change where possible. If a package-manager update is also required, make that another explicit review dimension rather than hiding it inside a regenerated lockfile.
Completed asset 1: the upgrade review pack
The fixture starts in a temporary directory with an empty npm user configuration and its own temporary cache. Installs use --ignore-scripts --no-audit --no-fund. The work retains the generated manifests, lockfiles, adapter, test program, command output, and resolved graph before removing the temporary installed tree and cache.
Those installation options bound this exercise. Disabling lifecycle scripts does not prove package safety, and disabling audit means there is no audit result to cite. A real application that needs installation scripts would require an appropriate review and test path for them.
The completed dependency comparison is:
| Review item | Baseline | Candidate | What the reviewer must notice |
|---|---|---|---|
| Direct package | strip-ansi 6.0.1 |
strip-ansi 7.1.2 |
Major-version boundary and module-loading compatibility |
| Indirect package | ansi-regex 5.0.1 |
ansi-regex 6.4.0 |
The resolved change extends beyond the single manifest dependency |
Direct dependency range on ansi-regex |
^5.0.1 |
^6.0.1 |
A range is not the same thing as the exact locked version |
| Declared Node engine in these lock entries | >=8 |
>=12 |
The current fixture runtime satisfies the declaration, but caller compatibility still fails |
| License recorded for both packages | MIT | MIT | No license-name change in the examined entries; this is not an organizational compliance approval |
| Package nodes excluding the fixture root | Two | Two | Two updates, no added or removed package nodes in this small graph |
The installed upstream package manifest also lists its own development tools. Those names are not automatically dependencies installed by this fixture. Review the generated project lock and the relevant dependency edges rather than treating every package name in an upstream repository as part of your runtime graph. Here the saved lock contains only the two package nodes described above, excluding the root fixture.
A declared minimum Node engine is also different from your organization’s supported-runtime policy. Satisfying >=12 does not establish that every consumer module format works, or recommend adopting that minimum runtime today. Keep the actual tested runtime, the package’s declaration, and the application’s supported environments as separate review fields.
The diff also changes resolved tarball URLs and integrity values. Those belong to the review record; do not hand-edit a lockfile to make it resemble the version you expected. Here the candidate’s indirect package resolves to 6.4.0, which is what the generated lockfile and installed package record show.
npm’s lockfile documentation describes the lock as recording the resolved tree and making tree changes reviewable. The fixture saves complete before-and-after files as well as readable diffs. Restoring a version number in package.json without restoring the matching tree specification would not recover that baseline.
GitHub’s dependency-review documentation likewise covers changes to direct and indirect dependencies in manifest and lockfile diffs, including known vulnerability information. No GitHub repository feature or check was enabled or run for this article. The local comparison is evidence about these files, not an account-side dependency-review result.
Exercise the consumer, not just the install
The original adapter is intentionally small:
const stripAnsi = require('strip-ansi');
module.exports = text => stripAnsi(text);
Its test has five fixed expected-output cases: plain text remains unchanged; red styling is removed; bold styling is removed; café ☕ remains intact; and the literal text literal [31m marker remains unchanged. The inputs are authored strings, not customer logs. Expected outputs are supplied explicitly rather than generated by the package being tested.
With the baseline installed, all five cases pass. The candidate installation also succeeds, but the same adapter and same test fail with TypeError: stripAnsi is not a function. On the recorded Node runtime, the required ESM package does not supply the callable value the adapter expects. The first plain-text case fails before the remaining assertions complete; the fixture does not claim five passing candidate cases or predict other runtimes’ errors.
The review therefore holds a candidate that installed successfully but broke the existing consumer contract. A green package-resolution step would have missed it. Reading the ESM release note gives the reviewer a reason to inspect that boundary, and exercising the boundary supplies the actual local failure.
Keep the candidate held while the application owner assesses an explicit ESM migration or adapter change and its caller contracts. It is not implemented in this case. Changing a synchronous consumer into an asynchronous one, changing exports, or rebuilding a bundle could affect other callers and require additional tests. Do not describe those possibilities as a verified fix merely because a migration guide exists.
The completed candidate disposition is therefore hold the update. The retained evidence identifies a loading/adapter incompatibility and a two-package resolved change. It does not establish security approval, performance parity, complete ANSI behavior, supported-platform coverage, or readiness to deploy.
Completed asset 2: reproduce recovery after the failure
Recovery is exercised inside the same disposable fixture. It does not reverse a real deployment or restore customer data. The original source adapter stays unchanged throughout this example, which makes the manifest-and-lock mismatch especially clear.
| Recovery step | Actual operation in the temporary fixture | Retained result |
|---|---|---|
| Incomplete restore | Restore baseline package.json only, leaving the candidate lockfile |
npm ci exits with EUSAGE because manifest and lockfile are out of sync |
| Explain the mismatch | Inspect the recorded error | Lock entries strip-ansi 7.1.2 and ansi-regex 6.4.0 do not satisfy the restored baseline requirements |
| Restore the pair | Restore the original package-lock.json alongside the original manifest |
Both files match their saved baseline hashes |
| Clean reinstall | Run npm ci with the fixture’s recorded installation options |
Installation exits successfully using the restored specification |
| Recheck the consumer | Run the unchanged adapter test again | The original five expected-output cases pass |
| Confirm source scope | Compare adapter hash with baseline | Adapter, manifest, and lockfile hashes all match the saved baseline |
npm’s ci documentation explains that it requires an existing lockfile, rejects an out-of-sync manifest and lockfile, and does not update those files to reconcile them. It also removes an existing node_modules tree before installation. Run such a recovery command only in the intended project or isolated test directory; it is not a harmless observation command.
The error is useful evidence here. Silently running a resolving install after restoring only the manifest would create a new dependency resolution, which might not be the exact baseline the reviewer intended to recover. The case instead restores the saved pair and checks the resulting consumer behavior.
The recovery receipt establishes matching saved file hashes and five passing cases on the recorded runtime; it does not establish identical binaries across other environments. The lock specifies package resolution; runtime, platform-specific behavior, build steps, environment variables, and external services can still matter. This fixture has no native build, application bundle, database, or external service state to recover.

Write the real recovery plan before approving an update
For a real release, identify the last known artifact, configuration, package specification, and runtime together. State who can halt rollout, what observable failure would trigger that decision, and what evidence is required after recovery. Keep the application owner and release owner distinct when the organization assigns those responsibilities separately.
The fictional application review note accompanying this fixture is complete: “Candidate held because the existing CommonJS adapter is incompatible on the recorded runtime. The isolated baseline pair has been restored and its five cases pass. An adapter migration needs a separate code change and regression review. No production change is approved.” This note is an authored handoff, not a message sent to a real team.
Rollback can be harder when an update changes stored data, file formats, generated assets, or an external protocol. Restoring an old lockfile cannot undo those effects. Check whether the older application can read any newly written state, whether an old artifact remains available, and whether a forward repair is safer than reversal. Do not promise recovery before examining those constraints.
Give the reviewer the motivation, resolved graph diff, upstream migration notes, consumer evidence, unresolved risks, and recovery boundary. State what was not checked.
Keep the failed candidate receipt, too. A passing restored test can otherwise conceal why the update was held. Name the exact command and runtime for each result so the reviewer can distinguish a rejected candidate from a recovered baseline. Passing a small test suite does not turn the absence of an audit into a vulnerability-free result.
For your next dependency update, inspect one indirect change and exercise one meaningful consumer boundary before accepting the package-manager status. Keep the baseline pair and the recovery evidence beside the candidate diff. More practical engineering guides are available from LandOffer.ai.



