Skip to content

refactor: introduce a NodeInstallation abstraction - #25266

Merged
Artur- merged 9 commits into
mainfrom
25258-node-installation-abstraction
Aug 21, 2026
Merged

Artur- merged 9 commits into
mainfrom
25258-node-installation-abstraction

Conversation

@totally-not-ai

Copy link
Copy Markdown
Contributor

Pure refactoring split out of #25261 so that the actual cleanup change can be reviewed on its own. No behaviour change.

NodeResolver built the node-v<version> paths of an auto-installed Node.js by hand in several places and scanned the install directory inline. That layout now lives in one place:

  • NodeInstallation — one installation directory: where its node binary and npm CLI script are, the version it is named after (getVersion()), and the version its binary actually reports (getInstalledVersion()). It has value semantics — equals/hashCode over the canonical directory — so two handles for the same installation compare as equal.
  • NodeInstallations — finds the installations of an install directory.

What that buys in NodeResolver:

  • the two branches that reuse an already installed version collapse into a single tryUseInstalled, which takes the version it requires as a parameter;
  • the versioned branch of findNpmCliScript turned out to be unreachable once the versioned directory itself is passed in, so it is gone together with the nodeVersion parameter and the second findNpmCliScript(installDir, null) lookup — what remains only searches the layouts of a global Node.js or an explicitly configured node folder;
  • getNodeExecutableForVersion, getInstallationDirectory and the local normalizeVersion helper are no longer needed;
  • findCompatibleInstalledVersion scans through NodeInstallations.findAll instead of listing files itself.

Tests: NodeInstallationTest and NodeInstallationsTest cover the new classes, and NodeResolverTest drives NodeResolver against a stubbed installation so the reuse path has coverage in the default suite rather than only in the slow one. Both new classes are added to the ClassesSerializableTest exclusions, alongside the other frontend build-tool classes.

Part of #25258. #25261 is stacked on top of this and adds the actual removal of old installations.

NodeResolver built the node-v<version> paths of an auto-installed
Node.js by hand in several places and scanned the install directory
inline. NodeInstallation now owns that layout - the directory, the node
binary, the npm CLI script, the version it is named after and the
version its binary reports - with value semantics, and NodeInstallations
finds the installations of an install directory.

With that in place, the two branches in NodeResolver that reuse an
already installed version collapse into one tryUseInstalled method, the
versioned branch of findNpmCliScript turns out to be dead and is gone
along with its second lookup, and getNodeExecutableForVersion,
getInstallationDirectory and the local normalizeVersion helper are no
longer needed.

No behaviour change. NodeResolverTest covers reusing an installation
without needing a real download.

Part of #25258
}

@Test
void equals_missingDirectories_isEqual() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped.

}

@Test
void equals_directoryReachedThroughAnotherPath_isEqual()

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped. equals_sameDirectory_isEqual covers the same thing.

}
File installDirectory = installation.getDirectory().getParentFile();
try {
// The directory name is only a claim, so compare the installation

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

retain also the comment that this is to test the binary works, in addition to comparing the versions

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded, it now reads: "Running the binary both validates that the installation actually works and tells which version it really is, as the directory name is only a claim."

* Creates an installation whose node binary reports the given version and
* which has an npm-cli.js where the versioned layout expects it.
*/
private NodeInstallation stubInstallation(String version)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't something similar already exist for other tests?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does — FrontendStubs already writes node and npm stubs, just in the unversioned <baseDir>/node/... layout that frontend-maven-plugin uses. I added FrontendStubs.createStubVersionedNode(version, baseDir) next to it for the node-<version>/... layout that our installer creates, and NodeResolverTest now just calls that.

@github-actions

github-actions Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
Contributor

Test Results

 1 378 files  +2   1 379 suites  +2   1h 29m 48s ⏱️ - 1m 4s
10 483 tests +6  10 416 ✅ +6  67 💤 ±0  0 ❌ ±0 
10 802 runs  +6  10 734 ✅ +6  68 💤 ±0  0 ❌ ±0 

Results for commit 5716916. ± Comparison against base commit c7cc4f2.

♻️ This comment has been updated with latest results.

…#25258)

FrontendStubs already knows how to write node and npm stubs, so it now
also covers the versioned layout that the Node.js installer of Flow
creates, and NodeResolverTest uses that instead of assembling the same
files itself.

Also dropped the equals cases that the first one already covers, and
spelled out in tryUseInstalled that running the binary is what validates
that the installation works, not just which version it is.

Part of #25258
}

// Check if any other compatible version is available
// Check if any other compatible version is available. Note that the

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this whole block a no-op and and can be removed as the exact node version is required and we find that using NodeInstallation.forVersion? If so, we should remove the dead code

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it was dead. findCompatibleInstalledVersion picked the newest supported version in the directory, but the installation was then only accepted if its binary reported the configured version — the very version that had just been looked for and not found. So it scanned and logged and then installed anyway. Removed, together with the method.

Two follow-ons from that: NodeResolver now only ever looks for the requested version, so NodeInstallations had no caller left and is gone from this PR (it comes back in #25261, where the cleanup uses it), and tryUseInstalled no longer needs the version passed in.

)

Javadoc reads `<baseDir>` and `<version>` as HTML tags and fails the
build on them, so they belong inside {@code}.

Part of #25258
@Artur- Artur- changed the title refactor: introduce a NodeInstallation abstraction (#25258) refactor: introduce a NodeInstallation abstraction Aug 21, 2026
totally-not-ai Bot and others added 4 commits August 21, 2026 06:55
…25258)

findCompatibleInstalledVersion picked the newest supported version in
the alternative directory, but the installation was then only accepted
if its binary reported the configured version - which is exactly the
version that had just been looked for and not found. The fallback could
therefore never succeed, it only scanned the directory and logged.

With it gone NodeResolver only ever looks for the requested version, so
NodeInstallations has no caller left and goes away too, and
tryUseInstalled no longer needs the version passed to it.

Part of #25258
Failing to make the node stub executable now fails the setup instead of
being ignored, since a stub that cannot be run is of no use to a test.
The platform check also moved into a single constant rather than being
repeated in every method that needs it.

Part of #25258
…ion' into 25258-node-installation-abstraction
Artur-
Artur- previously approved these changes Aug 21, 2026
…ble (#25258)

createStubNode and the dev server stub silently ignored whether the file
was created and made executable, which is the same problem that was just
fixed for the versioned node stub - and createStubNode is the one most
tests go through. All three now share a makeExecutable helper that says
what went wrong instead of leaving a stub that cannot be run.

Part of #25258
@Artur-
Artur- enabled auto-merge August 21, 2026 08:19
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

@Artur-
Artur- added this pull request to the merge queue Aug 21, 2026
Merged via the queue into main with commit 95905cf Aug 21, 2026
34 of 35 checks passed
@Artur-
Artur- deleted the 25258-node-installation-abstraction branch August 21, 2026 08:58
@vaadin-bot

Copy link
Copy Markdown
Collaborator

This ticket/PR has been released with Vaadin 25.3.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants