This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new da780d65fb feat: Add WorkspaceReader SPI to maven-api-spi
da780d65fb is described below
commit da780d65fbf1ce498900e820136cbe7201b3b446
Author: Guillaume Nodet <[email protected]>
AuthorDate: Mon Nov 9 17:39:39 2026 +0100
feat: Add WorkspaceReader SPI to maven-api-spi
- Introduce `WorkspaceReader` SPI in `maven-api-spi` with `findArtifact()`,
`findVersions()`, and default `findModel()` returning `Optional<Model>` — uses
Maven 4 API types exclusively, no `maven-resolver-api` dependency
- `SpiWorkspaceReaderAdapter` in `maven-core` bridges SPI implementations
into the resolver workspace reader chain, including `findModel()` dispatch via
`MavenChainedWorkspaceReader`
- Core-extension SPI readers are discovered before `buildGraph()` via
`Injector.getInstance(Key<List<WorkspaceReader>>)` (not `lookupList()`, which
misses beans registered via the DI bridge in `BridgeInjectorImpl`)
- Project-scoped SPI readers are wired after `buildGraph()` in
`setupWorkspaceReader()` with identity-based deduplication
- IT `mng-8766` verifies SPI reader discovery as a core extension,
`findArtifact()` consultation, and end-to-end `findModel()` wiring using a
fully synthetic artifact
Solves https://github.com/apache/maven/issues/13515
---
.../org/apache/maven/api/spi/WorkspaceReader.java | 93 ++++++++++
.../main/java/org/apache/maven/DefaultMaven.java | 63 ++++++-
.../maven/resolver/SpiWorkspaceReaderAdapter.java | 204 +++++++++++++++++++++
.../it/MavenITmng8766SpiWorkspaceReaderTest.java | 92 ++++++++++
.../extension/pom.xml | 58 ++++++
.../its/extensions/TestSpiWorkspaceReader.java | 106 +++++++++++
.../project/.mvn/extensions.xml | 28 +++
.../mng-8766-spi-workspace-reader/project/pom.xml | 50 +++++
8 files changed, 692 insertions(+), 2 deletions(-)
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/WorkspaceReader.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/WorkspaceReader.java
new file mode 100644
index 0000000000..e4f8dda8a6
--- /dev/null
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/WorkspaceReader.java
@@ -0,0 +1,93 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.spi;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.maven.api.Artifact;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.di.Named;
+import org.apache.maven.api.model.Model;
+
+/**
+ * SPI for IDE and tool integrators to provide workspace artifact resolution.
+ *
+ * <p>Implementations are discovered via DI and are automatically bridged into
the
+ * resolver's workspace reader chain, replacing the need for the internal
+ * {@code @Named("ide")} resolver {@code WorkspaceReader} mechanism.
+ *
+ * <p>Implementations must be annotated with {@link Named} and can be
registered either as
+ * <em>core extensions</em> (via {@code .mvn/extensions.xml}) or as
<em>project-scoped
+ * extensions</em> (declared in a module's {@code pom.xml} {@code
<extensions>} block).
+ * Core-extension readers are active from the very start of the build (before
POM resolution),
+ * while project-scoped readers become active after the project graph has been
built.
+ *
+ * <p>SPI workspace readers are intentionally <em>excluded</em> from plugin
and extension
+ * resolution to avoid stale classloader issues: plugin realms are cached in a
+ * {@code @Singleton} cache and cannot be invalidated within a session, so
resolving
+ * plugins from workspace sources would cause stale classes if workspace
sources change.
+ *
+ * <p>Unlike the legacy {@code org.eclipse.aether.repository.WorkspaceReader},
this SPI
+ * uses Maven 4 API types only (no maven-resolver-api dependency required).
+ *
+ * @since 4.2.0
+ */
+@Experimental
+@Consumer
+@Named
+public interface WorkspaceReader extends SpiService {
+
+ /**
+ * Finds the path on disk for the given artifact in the workspace, if
present.
+ *
+ * @param artifact the artifact to look up, never {@code null}
+ * @return the path to the artifact file, or empty if not found in
workspace
+ */
+ Optional<Path> findArtifact(Artifact artifact);
+
+ /**
+ * Returns the list of available versions for the given artifact in the
workspace.
+ *
+ * @param artifact the artifact to look up (version is ignored), never
{@code null}
+ * @return list of available versions, may be empty
+ */
+ List<String> findVersions(Artifact artifact);
+
+ /**
+ * Returns the model (POM) for the given artifact from the workspace, if
available.
+ *
+ * <p>This method allows IDE integrators to provide project models built
directly from
+ * their own sources (e.g. Eclipse manifests, Gradle metadata) without
writing an
+ * intermediate XML file for Maven to parse. The returned model bypasses
+ * {@code ModelProcessor} entirely and is used as-is by the resolver.
+ *
+ * <p>The default implementation returns empty, preserving backward
compatibility for
+ * implementations that only provide artifact resolution.
+ *
+ * @param artifact the artifact whose model to look up, never {@code null}
+ * @return the model, or empty if not available in the workspace
+ * @since 4.2.0
+ */
+ default Optional<Model> findModel(Artifact artifact) {
+ return Optional.empty();
+ }
+}
diff --git a/impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java
b/impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java
index e7b6e33468..9cd32da972 100644
--- a/impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java
+++ b/impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java
@@ -30,6 +30,7 @@
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
+import java.util.IdentityHashMap;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
@@ -46,6 +47,8 @@
import org.apache.maven.api.services.Lookup;
import org.apache.maven.api.services.LookupException;
import org.apache.maven.artifact.ArtifactUtils;
+import org.apache.maven.di.Injector;
+import org.apache.maven.di.Key;
import org.apache.maven.execution.BuildResumptionAnalyzer;
import org.apache.maven.execution.BuildResumptionDataRepository;
import org.apache.maven.execution.BuildResumptionPersistenceException;
@@ -71,6 +74,7 @@
import org.apache.maven.project.MavenProject;
import org.apache.maven.resolver.MavenChainedWorkspaceReader;
import org.apache.maven.resolver.RepositorySystemSessionFactory;
+import org.apache.maven.resolver.SpiWorkspaceReaderAdapter;
import org.apache.maven.session.scope.internal.SessionScope;
import org.eclipse.aether.RepositorySystemSession;
import org.eclipse.aether.RepositorySystemSession.CloseableSession;
@@ -248,6 +252,20 @@ private MavenExecutionResult doExecute(
return addExceptionToResult(result, e);
}
+ // Register SPI workspace readers from the global container before
project graph building.
+ // Core extensions declared in .mvn/extensions.xml are loaded into the
global container
+ // before project scanning begins. Without this early registration,
workspace readers from
+ // core extensions would miss the POM resolution phase (buildGraph),
which resolves
+ // dependency POMs before setupWorkspaceReader() is called.
Project-scoped readers (from
+ // per-project extensions) are added again in setupWorkspaceReader()
after buildGraph().
+ // Note: SPI components registered by core extensions are discovered
via the maven DI
+ // Injector (not Plexus lookupList) because the Guice binder used to
bridge DI beans to
+ // Sisu/Plexus is only active during the initial container
configuration phase; late-bound
+ // extension beans are only reliably accessible through the Injector's
internal registry.
+ for (org.apache.maven.api.spi.WorkspaceReader spiReader :
getSpiWorkspaceReadersFromInjector()) {
+ chainedWorkspaceReader.addReader(new
SpiWorkspaceReaderAdapter(spiReader));
+ }
+
eventCatapult.fire(ExecutionEvent.Type.ProjectDiscoveryStarted,
session, null);
Result<? extends ProjectDependencyGraph> graphResult =
buildGraph(session);
@@ -343,17 +361,58 @@ private void setupWorkspaceReader(MavenSession session,
MavenChainedWorkspaceRea
// 1) Reactor workspace reader
WorkspaceReader reactorReader = lookup.lookup(WorkspaceReader.class,
ReactorReader.HINT);
workspaceReaders.add(reactorReader);
- // 2) Repository system session-scoped workspace reader (contains ide
and exec request reader)
+ // 2) Repository system session-scoped workspace reader (contains ide,
exec request reader,
+ // and SPI readers already registered from the global container
before buildGraph()).
for (WorkspaceReader repoWorkspaceReader :
chainedWorkspaceReader.getReaders()) {
if (repoWorkspaceReader != null && repoWorkspaceReader !=
reactorReader) {
workspaceReaders.add(repoWorkspaceReader);
}
}
- // 3) .. n) Project-scoped workspace readers
+ // 3) .. n) Project-scoped legacy workspace readers
(org.eclipse.aether)
workspaceReaders.addAll(getProjectScopedExtensionComponents(session.getProjects(),
WorkspaceReader.class));
+ // n+1) Project-scoped SPI workspace readers not yet registered (those
loaded by project-level
+ // build extensions, not core extensions). Core-extension SPI
readers are already
+ // registered via getSpiWorkspaceReadersFromInjector() before
buildGraph().
+ // Collect already-registered SPI delegates (by identity) to
avoid wrapping the same
+ // reader twice.
+ Set<org.apache.maven.api.spi.WorkspaceReader> wrappedDelegates =
+ Collections.newSetFromMap(new IdentityHashMap<>());
+ workspaceReaders.stream()
+ .filter(r -> r instanceof SpiWorkspaceReaderAdapter)
+ .forEach(r ->
wrappedDelegates.add(((SpiWorkspaceReaderAdapter) r).getDelegate()));
+ for (org.apache.maven.api.spi.WorkspaceReader spiReader :
getProjectScopedExtensionComponents(
+ session.getProjects(),
org.apache.maven.api.spi.WorkspaceReader.class)) {
+ if (!wrappedDelegates.contains(spiReader)) {
+ workspaceReaders.add(new SpiWorkspaceReaderAdapter(spiReader));
+ }
+ }
chainedWorkspaceReader.setReaders(workspaceReaders);
}
+ /**
+ * Returns all {@link org.apache.maven.api.spi.WorkspaceReader SPI
workspace readers} registered
+ * in the maven DI injector (which is the source of truth for
core-extension DI beans).
+ *
+ * <p>SPI components registered by core extensions are discovered via the
maven DI {@link Injector}
+ * rather than via {@link
org.apache.maven.api.services.Lookup#lookupList}, because the Guice
+ * {@code Binder} used to bridge maven-DI beans into Sisu/Plexus is only
active during the initial
+ * container configuration phase. Beans that are discovered later — during
+ * {@code PlexusContainer.discoverComponents()} for each core extension —
are registered into the
+ * {@code InjectorImpl}'s internal binding map but may not be successfully
bridged into Guice/Sisu,
+ * so a plain Plexus {@code lookupList} would return an empty list for
them.</p>
+ *
+ * @return list of SPI workspace readers (never {@code null}; empty if
none registered)
+ */
+ private List<org.apache.maven.api.spi.WorkspaceReader>
getSpiWorkspaceReadersFromInjector() {
+ try {
+ Injector injector = lookup.lookup(Injector.class);
+ return injector.getInstance(new
Key<List<org.apache.maven.api.spi.WorkspaceReader>>() {});
+ } catch (Exception e) {
+ logger.debug("No maven DI injector available, cannot look up SPI
WorkspaceReaders: {}", e.getMessage());
+ return List.of();
+ }
+ }
+
private void afterSessionStart(MavenSession session) throws
MavenExecutionException {
callListeners(session,
AbstractMavenLifecycleParticipant::afterSessionStart);
}
diff --git
a/impl/maven-core/src/main/java/org/apache/maven/resolver/SpiWorkspaceReaderAdapter.java
b/impl/maven-core/src/main/java/org/apache/maven/resolver/SpiWorkspaceReaderAdapter.java
new file mode 100644
index 0000000000..7a12a7dee3
--- /dev/null
+++
b/impl/maven-core/src/main/java/org/apache/maven/resolver/SpiWorkspaceReaderAdapter.java
@@ -0,0 +1,204 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.resolver;
+
+import java.io.File;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.maven.api.ArtifactCoordinates;
+import org.apache.maven.api.Version;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.model.Model;
+import org.apache.maven.impl.resolver.MavenWorkspaceReader;
+import org.eclipse.aether.artifact.Artifact;
+import org.eclipse.aether.repository.WorkspaceRepository;
+
+/**
+ * Bridge adapter that wraps an {@link
org.apache.maven.api.spi.WorkspaceReader SPI WorkspaceReader}
+ * into a {@link MavenWorkspaceReader}.
+ *
+ * <p>This adapter translates between resolver {@link Artifact} and Maven API
+ * {@link org.apache.maven.api.Artifact} types, allowing SPI implementations
to work
+ * with Maven 4 API types exclusively while being integrated into the
resolver's
+ * workspace reader chain. By implementing {@link MavenWorkspaceReader}, the
adapter
+ * also participates in model resolution: {@link #findModel(Artifact)}
delegates directly
+ * to {@link
org.apache.maven.api.spi.WorkspaceReader#findModel(org.apache.maven.api.Artifact)},
+ * which returns a pre-built {@link Model} (bypassing {@code ModelProcessor}
entirely).
+ *
+ * @since 4.2.0
+ */
+public class SpiWorkspaceReaderAdapter implements MavenWorkspaceReader {
+
+ private final org.apache.maven.api.spi.WorkspaceReader delegate;
+ private final WorkspaceRepository repository;
+
+ public SpiWorkspaceReaderAdapter(org.apache.maven.api.spi.WorkspaceReader
delegate) {
+ this.delegate = delegate;
+ this.repository = new WorkspaceRepository("spi-" +
delegate.getClass().getSimpleName());
+ }
+
+ @Override
+ public WorkspaceRepository getRepository() {
+ return repository;
+ }
+
+ @Override
+ public File findArtifact(Artifact artifact) {
+ Optional<Path> result = delegate.findArtifact(toApiArtifact(artifact));
+ return result.map(Path::toFile).orElse(null);
+ }
+
+ @Override
+ public List<String> findVersions(Artifact artifact) {
+ return delegate.findVersions(toApiArtifact(artifact));
+ }
+
+ @Override
+ public Model findModel(Artifact artifact) {
+ return delegate.findModel(toApiArtifact(artifact)).orElse(null);
+ }
+
+ /**
+ * Returns the underlying SPI workspace reader.
+ */
+ public org.apache.maven.api.spi.WorkspaceReader getDelegate() {
+ return delegate;
+ }
+
+ /**
+ * Creates a lightweight Maven API {@link org.apache.maven.api.Artifact}
from a resolver artifact
+ * without requiring an active session.
+ */
+ private static org.apache.maven.api.Artifact toApiArtifact(Artifact
artifact) {
+ return new LightweightApiArtifact(artifact);
+ }
+
+ /**
+ * A lightweight implementation of {@link org.apache.maven.api.Artifact}
that wraps a resolver artifact
+ * for the purpose of passing artifact coordinates to SPI workspace
readers.
+ */
+ private static class LightweightApiArtifact implements
org.apache.maven.api.Artifact {
+ private final Artifact artifact;
+ private final String key;
+
+ LightweightApiArtifact(Artifact artifact) {
+ this.artifact = artifact;
+ this.key = artifact.getGroupId()
+ + ':'
+ + artifact.getArtifactId()
+ + ':'
+ + artifact.getExtension()
+ + (artifact.getClassifier().isEmpty() ? "" : ":" +
artifact.getClassifier())
+ + ':'
+ + artifact.getVersion();
+ }
+
+ @Override
+ public String key() {
+ return key;
+ }
+
+ @Nonnull
+ @Override
+ public String groupId() {
+ return artifact.getGroupId();
+ }
+
+ @Nonnull
+ @Override
+ public String artifactId() {
+ return artifact.getArtifactId();
+ }
+
+ @Nonnull
+ @Override
+ public Version version() {
+ return new StringVersion(artifact.getVersion());
+ }
+
+ @Nonnull
+ @Override
+ public Version baseVersion() {
+ return new StringVersion(artifact.getBaseVersion());
+ }
+
+ @Nonnull
+ @Override
+ public String extension() {
+ return artifact.getExtension();
+ }
+
+ @Nonnull
+ @Override
+ public String classifier() {
+ return artifact.getClassifier();
+ }
+
+ @Override
+ public boolean isSnapshot() {
+ return artifact.isSnapshot();
+ }
+
+ @Nonnull
+ @Override
+ public ArtifactCoordinates toCoordinates() {
+ throw new UnsupportedOperationException("Lightweight artifact
wrapper does not support toCoordinates(); "
+ + "use Session.createArtifactCoordinates() instead");
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ return o instanceof org.apache.maven.api.Artifact a &&
key.equals(a.key());
+ }
+
+ @Override
+ public int hashCode() {
+ return key.hashCode();
+ }
+
+ @Override
+ public String toString() {
+ return key;
+ }
+ }
+
+ /**
+ * Simple {@link Version} implementation that wraps a version string.
+ *
+ * <p><b>Note on ordering:</b> {@link #compareTo(Version)} uses
lexicographic string
+ * comparison, which does <em>not</em> give correct semantic version
ordering for
+ * multi-digit components (e.g. {@code "10"} sorts before {@code "9"}).
This wrapper
+ * is used solely to pass artifact coordinates to SPI workspace readers;
callers should
+ * not rely on {@code compareTo} for correct Maven version ordering. Use
a proper
+ * {@link org.apache.maven.api.services.VersionParser} when version
ordering matters.</p>
+ */
+ private record StringVersion(String version) implements Version {
+ @Override
+ public int compareTo(Version o) {
+ return version.compareTo(o.toString());
+ }
+
+ @Override
+ public String toString() {
+ return version;
+ }
+ }
+}
diff --git
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8766SpiWorkspaceReaderTest.java
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8766SpiWorkspaceReaderTest.java
new file mode 100644
index 0000000000..7e3efa2139
--- /dev/null
+++
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8766SpiWorkspaceReaderTest.java
@@ -0,0 +1,92 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.it;
+
+import java.nio.file.Path;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Integration test for the {@code WorkspaceReader} SPI in maven-api-spi
(MNG-8766).
+ *
+ * <p>Verifies that SPI workspace readers are:
+ * <ol>
+ * <li>Discovered via DI and active during the build session</li>
+ * <li>Consulted for regular artifact resolution (findArtifact,
findVersions)</li>
+ * <li>Consulted for model resolution via findModel() — the pre-built {@link
org.apache.maven.api.model.Model}
+ * returned by the SPI is passed directly through {@code
SpiWorkspaceReaderAdapter}
+ * to the resolver, bypassing {@code ModelProcessor} entirely</li>
+ * </ol>
+ *
+ * <p>The test extension ({@code TestSpiWorkspaceReader}) serves a completely
synthetic artifact
+ * ({@code org.apache.maven.its.mng8766:virtual-dep:1.0}) that does not exist
in any repository.
+ * The project POM declares a dependency on this artifact, so Maven must
consult the workspace reader
+ * for both the artifact file ({@code findArtifact}) and the model ({@code
findModel}).
+ *
+ * @since 4.2.0
+ */
+class MavenITmng8766SpiWorkspaceReaderTest extends
AbstractMavenIntegrationTestCase {
+
+ @Test
+ void testSpiWorkspaceReaderDiscoveredAndConsulted() throws Exception {
+ Path testDir = extractResources("mng-8766-spi-workspace-reader");
+
+ // First, install the extension
+ Verifier verifier = newVerifier(testDir.resolve("extension"));
+ verifier.addCliArguments("-DmavenVersion=" +
verifier.getMavenVersion(), "install");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ // Run the project that uses the extension — compile triggers artifact
+ model resolution
+ verifier = newVerifier(testDir.resolve("project"));
+ verifier.addCliArgument("compile");
+ verifier.execute();
+ verifier.verifyErrorFreeLog();
+
+ List<String> logLines = verifier.loadLogLines();
+
+ // Verify the SPI workspace reader was created (proves DI discovery
works)
+ verifier.verifyTextInLog("[SPI-WR] created");
+
+ // Verify the SPI workspace reader was consulted during artifact
resolution
+ boolean hasFindArtifactCalls = logLines.stream().anyMatch(line ->
line.contains("[SPI-WR] findArtifact("));
+ assertTrue(hasFindArtifactCalls, "SPI workspace reader should be
consulted during artifact resolution");
+
+ // Verify findModel() was called for the synthetic dependency —
+ // this proves SpiWorkspaceReaderAdapter implements
MavenWorkspaceReader and is
+ // correctly wired into the MavenChainedWorkspaceReader dispatch chain.
+ boolean hasFindModelCall = logLines.stream()
+ .anyMatch(line -> line.contains("[SPI-WR] findModel(")
+ &&
line.contains("org.apache.maven.its.mng8766:virtual-dep"));
+ assertTrue(
+ hasFindModelCall,
+ "SPI workspace reader findModel() should be called for the
synthetic dependency "
+ + "(org.apache.maven.its.mng8766:virtual-dep:1.0)");
+
+ // Verify the synthetic POM was returned and accepted (reader logs
this on success)
+ boolean hasModelReturned =
+ logLines.stream().anyMatch(line -> line.contains("[SPI-WR]
findModel: returning synthetic POM for"));
+ assertTrue(
+ hasModelReturned,
+ "SPI workspace reader findModel() should have returned a
synthetic POM for virtual-dep");
+ }
+}
diff --git
a/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/pom.xml
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/pom.xml
new file mode 100644
index 0000000000..80ae7f82fd
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/pom.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.maven.its.mng8766</groupId>
+ <artifactId>spi-workspace-reader</artifactId>
+ <version>0.1</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Integration Test :: spi-workspace-reader</name>
+ <description>SPI WorkspaceReader extension for IDE workspace artifact
resolution</description>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-api-spi</artifactId>
+ <version>${mavenVersion}</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-api</artifactId>
+ <version>2.0.16</version>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.14.0</version>
+ <configuration>
+ <proc>full</proc>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
diff --git
a/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/src/main/java/org/apache/maven/its/extensions/TestSpiWorkspaceReader.java
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/src/main/java/org/apache/maven/its/extensions/TestSpiWorkspaceReader.java
new file mode 100644
index 0000000000..fcf5f90166
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/extension/src/main/java/org/apache/maven/its/extensions/TestSpiWorkspaceReader.java
@@ -0,0 +1,106 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.its.extensions;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.maven.api.Artifact;
+import org.apache.maven.api.di.Named;
+import org.apache.maven.api.model.Model;
+import org.apache.maven.api.spi.WorkspaceReader;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@Named("test-ide")
+public class TestSpiWorkspaceReader implements WorkspaceReader {
+
+ private static final Logger log =
LoggerFactory.getLogger(TestSpiWorkspaceReader.class);
+
+ /**
+ * GAV of the synthetic artifact served by this workspace reader.
+ * The test project declares a dependency on this artifact.
+ */
+ private static final String SYNTHETIC_GROUP =
"org.apache.maven.its.mng8766";
+
+ private static final String SYNTHETIC_ARTIFACT = "virtual-dep";
+ private static final String SYNTHETIC_VERSION = "1.0";
+
+ public TestSpiWorkspaceReader() {
+ log.info("[SPI-WR] created");
+ }
+
+ @Override
+ public Optional<Path> findArtifact(Artifact artifact) {
+ log.info("[SPI-WR] findArtifact({})", artifact.key());
+ if (isSyntheticArtifact(artifact)) {
+ try {
+ // Return a minimal (empty) jar file so the resolver can
satisfy the dependency
+ Path jar = Files.createTempFile("mng8766-virtual-dep", ".jar");
+ jar.toFile().deleteOnExit();
+ // Write a valid empty ZIP/jar (4 bytes:
end-of-central-directory signature)
+ try (OutputStream os = Files.newOutputStream(jar)) {
+ os.write(new byte[] {0x50, 0x4B, 0x05, 0x06, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0});
+ }
+ log.info("[SPI-WR] findArtifact: returning synthetic jar for
{}", artifact.key());
+ return Optional.of(jar);
+ } catch (IOException e) {
+ log.warn("[SPI-WR] could not create synthetic jar: {}",
e.getMessage());
+ }
+ }
+ return Optional.empty();
+ }
+
+ @Override
+ public List<String> findVersions(Artifact artifact) {
+ log.info("[SPI-WR] findVersions({})", artifact.key());
+ if (SYNTHETIC_GROUP.equals(artifact.groupId()) &&
SYNTHETIC_ARTIFACT.equals(artifact.artifactId())) {
+ return Collections.singletonList(SYNTHETIC_VERSION);
+ }
+ return Collections.emptyList();
+ }
+
+ @Override
+ public Optional<Model> findModel(Artifact artifact) {
+ log.info("[SPI-WR] findModel({})", artifact.key());
+ if (isSyntheticArtifact(artifact)) {
+ Model model = Model.newBuilder()
+ .modelVersion("4.0.0")
+ .groupId(SYNTHETIC_GROUP)
+ .artifactId(SYNTHETIC_ARTIFACT)
+ .version(SYNTHETIC_VERSION)
+ .packaging("jar")
+ .build();
+ log.info("[SPI-WR] findModel: returning synthetic POM for {}",
artifact.key());
+ return Optional.of(model);
+ }
+ return Optional.empty();
+ }
+
+ private static boolean isSyntheticArtifact(Artifact artifact) {
+ return SYNTHETIC_GROUP.equals(artifact.groupId())
+ && SYNTHETIC_ARTIFACT.equals(artifact.artifactId())
+ && SYNTHETIC_VERSION.equals(artifact.version().toString());
+ }
+}
diff --git
a/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/.mvn/extensions.xml
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/.mvn/extensions.xml
new file mode 100644
index 0000000000..0b71d00e7a
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/.mvn/extensions.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<extensions>
+ <extension>
+ <groupId>org.apache.maven.its.mng8766</groupId>
+ <artifactId>spi-workspace-reader</artifactId>
+ <version>0.1</version>
+ </extension>
+</extensions>
diff --git
a/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/pom.xml
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/pom.xml
new file mode 100644
index 0000000000..363f35408b
--- /dev/null
+++
b/its/core-it-suite/src/test/resources/mng-8766-spi-workspace-reader/project/pom.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.maven.its.mng8766</groupId>
+ <artifactId>test</artifactId>
+ <version>0.1</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Integration Test :: mng-8766</name>
+ <description>Verify that SPI WorkspaceReader is discovered and consulted for
artifact resolution.</description>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.13.2</version>
+ <scope>test</scope>
+ </dependency>
+ <!--
+ Synthetic dependency served entirely by the SPI workspace reader
(TestSpiWorkspaceReader).
+ It does not exist in any remote or local repository; the workspace
reader provides both the
+ artifact file (findArtifact) and the model (findModel), proving
end-to-end wiring works.
+ -->
+ <dependency>
+ <groupId>org.apache.maven.its.mng8766</groupId>
+ <artifactId>virtual-dep</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+
+</project>