Data Model and Tree Structures

/**
 * Represents a Maven POM with all its metadata and dependencies
 * The cacheable representation of POMs
 */
@Value
@With
@Builder
public class Pom implements Serializable {
    /**
     * Get project group ID
     */
    public @Nullable String getGroupId();
    
    /**
     * Get project artifact ID
     */
    public String getArtifactId();
    
    /**
     * Get project version
     */
    public @Nullable String getVersion();
    
    /**
     * Get project properties
     */
    public Map<String, String> getProperties();
    
    /**
     * Get project dependencies
     */
    public List<Dependency> getDependencies();
    
    /**
     * Get managed dependencies
     */
    public List<ManagedDependency> getDependencyManagement();
    
    /**
     * Get build plugins
     */
    public List<Plugin> getPlugins();
    
    /**
     * Get parent POM reference
     */
    public @Nullable Parent getParent();
}

/**
 * Fully resolved POM with dependency resolution completed
 * Internal data structure - use MavenResolutionResult for dependency access
 */
public class ResolvedPom {
    /**
     * Get the underlying POM
     */
    public Pom getPom();
    
    /**
     * Get effective properties after resolution
     */
    public Map<String, String> getProperties();
    
    /**
     * Get Maven repositories used for resolution
     */
    public List<MavenRepository> getRepositories();
}

/**
 * Contains resolved Maven project information attached to XML documents
 * Primary interface for accessing Maven dependency information
 */
public class MavenResolutionResult {
    /**
     * Get the resolved POM
     */
    public ResolvedPom getPom();
    
    /**
     * Get resolved dependencies grouped by scope
     */
    public Map<Scope, List<ResolvedDependency>> getDependencies();
    
    /**
     * Find dependencies matching group and artifact ID
     */
    public List<ResolvedDependency> findDependencies(String groupId, String artifactId);
    
    /**
     * Get Maven modules if this is a multi-module project
     */
    public Map<Path, ResolvedPom> getModules();
    
    /**
     * Find module by path
     */
    public @Nullable ResolvedPom findModule(Path path);
}

// Access resolution result from parsed document
Xml.Document pomDocument = (Xml.Document) parsedFiles.get(0);
MavenResolutionResult result = pomDocument.getMarkers()
    .findFirst(MavenResolutionResult.class)
    .orElse(null);

if (result != null) {
    ResolvedPom resolvedPom = result.getPom();
    Pom pom = resolvedPom.getPom();
    
    // Access project information
    String groupId = pom.getGroupId();
    String artifactId = pom.getArtifactId();
    String version = pom.getVersion();
    System.out.println("Project: " + groupId + ":" + artifactId + ":" + version);
    
    // Access dependencies by scope
    Map<Scope, List<ResolvedDependency>> dependenciesByScope = result.getDependencies();
    for (Map.Entry<Scope, List<ResolvedDependency>> entry : dependenciesByScope.entrySet()) {
        Scope scope = entry.getKey();
        List<ResolvedDependency> dependencies = entry.getValue();
        System.out.println("Dependencies in " + scope + " scope:");
        for (ResolvedDependency dep : dependencies) {
            System.out.println("  " + dep.getGroupId() + ":" + dep.getArtifactId() + ":" + dep.getVersion());
        }
    }
}

/**
 * Represents Maven groupId:artifactId coordinate
 */
@Value
public class GroupArtifact implements Serializable {
    String groupId;
    String artifactId;
    
    /**
     * Create from string in format "groupId:artifactId"
     */
    public static GroupArtifact fromCoordinates(String coordinates);
}

/**
 * Represents Maven groupId:artifactId:version coordinate
 */
@Value  
public class GroupArtifactVersion implements Serializable {
    String groupId;
    String artifactId;
    @Nullable String version;
    
    /**
     * Create from string in format "groupId:artifactId:version"
     */
    public static GroupArtifactVersion fromCoordinates(String coordinates);
    
    /**
     * Convert to GroupArtifact
     */
    public GroupArtifact asGroupArtifact();
}

/**
 * Resolved GAV with effective version determined
 */
@Value
public class ResolvedGroupArtifactVersion implements Serializable {
    String groupId;
    String artifactId;
    String version;          // Resolved effective version
    @Nullable String datedSnapshotVersion;  // For snapshot versions
    
    /**
     * Get the repository where this was resolved from
     */
    public @Nullable MavenRepository getRepository();
}

/**
 * Represents a Maven dependency
 */
@Value
@With
@Builder
public class Dependency implements Serializable, Attributed {
    String groupId;
    String artifactId;
    @Nullable String version;
    @Nullable String classifier;
    @Nullable String type;           // Default: "jar"
    @Nullable Scope scope;           // Default: Compile
    @Nullable Boolean optional;      // Default: false
    List<GroupArtifact> exclusions;  // Dependencies to exclude
    
    /**
     * Convert to coordinate representation
     */
    public GroupArtifactVersion getGav();
    
    /**
     * Check if this dependency matches given coordinates
     */
    public boolean matches(String groupId, String artifactId);
}

/**
 * Fully resolved dependency with transitive dependencies
 */
@Value
public class ResolvedDependency implements Serializable {
    ResolvedGroupArtifactVersion gav;
    @Nullable String classifier;
    @Nullable String type;
    Scope scope;
    @Nullable Boolean optional;
    List<ResolvedDependency> dependencies;  // Transitive dependencies
    
    /**
     * Get direct coordinate access
     */
    public String getGroupId();
    public String getArtifactId();
    public String getVersion();
    
    /**
     * Find transitive dependency
     */
    public @Nullable ResolvedDependency findDependency(String groupId, String artifactId);
    
    /**
     * Get all dependencies recursively (depth-first)
     */
    public List<ResolvedDependency> getDependenciesRecursively();
}

// Create a new dependency
Dependency junitDependency = Dependency.builder()
    .groupId("org.junit.jupiter")
    .artifactId("junit-jupiter")
    .version("5.8.2")
    .scope(Scope.Test)
    .build();

// Work with resolved dependencies
List<ResolvedDependency> springCoreDeps = result.findDependencies("org.springframework", "spring-core");
ResolvedDependency resolvedDep = springCoreDeps.isEmpty() ? null : springCoreDeps.get(0);
if (resolvedDep != null) {
    System.out.println("Spring Core version: " + resolvedDep.getVersion());
    
    // Check transitive dependencies
    List<ResolvedDependency> transitives = resolvedDep.getDependenciesRecursively();
    for (ResolvedDependency transitive : transitives) {
        System.out.println("  Transitive: " + transitive.getGroupId() + ":" + transitive.getArtifactId());
    }
}

/**
 * Interface for managed dependencies in dependencyManagement section
 */
public interface ManagedDependency {
    String getGroupId();
    String getArtifactId(); 
    @Nullable String getVersion();
    @Nullable String getClassifier();
    @Nullable String getType();
    @Nullable Scope getScope();
    List<GroupArtifact> getExclusions();
}

/**
 * Resolved managed dependency implementation
 */
@Value
public class ResolvedManagedDependency implements ManagedDependency {
    ResolvedGroupArtifactVersion gav;
    @Nullable String classifier;
    @Nullable String type;
    @Nullable Scope scope;
    List<GroupArtifact> exclusions;
    
    // Implements all ManagedDependency methods
}

/**
 * Maven dependency scopes with precedence and behavior rules
 */
public enum Scope {
    Compile,    // Default scope, available in all classpaths
    Test,       // Only available for test compilation and execution  
    Runtime,    // Not required for compilation but needed for execution
    Provided,   // Expected to be provided by runtime environment
    System,     // Similar to provided but must be explicitly provided
    Import;     // Only supported on dependency of type 'pom' in dependencyManagement
    
    /**
     * Check if this scope is wider than another scope
     */
    public boolean isInClasspathOf(Scope other);
    
    /**
     * Convert to Gradle equivalent scope
     */
    public String toGradleConfiguration();
}

/**
 * Maven version representation and comparison
 */
public class Version implements Comparable<Version> {
    /**
     * Parse version string
     */
    public static Version valueOf(String version);
    
    /**
     * Check if this is a snapshot version
     */
    public boolean isSnapshot();
    
    /**
     * Get version components
     */
    public List<String> getComponents();
    
    /**
     * Compare versions according to Maven rules
     */
    @Override
    public int compareTo(Version other);
}

/**
 * Represents Maven repository configuration
 */
@Value
@Builder
public class MavenRepository implements Serializable {
    String id;
    String uri; 
    boolean releases;        // Allow release artifacts
    boolean snapshots;       // Allow snapshot artifacts
    @Nullable String username;
    @Nullable String password;
    
    /**
     * Check if this repository allows release artifacts
     */
    public boolean acceptsReleases();
    
    /**
     * Check if this repository allows snapshot artifacts  
     */
    public boolean acceptsSnapshots();
}

/**
 * Represents Maven plugin configuration
 */
@Value
@With
@Builder
public class Plugin implements Serializable {
    String groupId;          // Default: "org.apache.maven.plugins"
    String artifactId;
    @Nullable String version;
    @Nullable Object configuration;    // Plugin-specific configuration
    List<PluginExecution> executions;
    List<Dependency> dependencies;     // Plugin dependencies
    
    /**
     * Get full plugin coordinate
     */
    public GroupArtifactVersion getGav();
    
    /**
     * Check if this plugin matches coordinates
     */
    public boolean matches(String groupId, String artifactId);
}

/**
 * Represents parent POM reference
 */
@Value
public class Parent {
    GroupArtifactVersion gav;
    @Nullable String relativePath;   // Default: "../pom.xml"
    
    public String getGroupId();
    public String getArtifactId();
    public String getVersion();
}

/**
 * Represents project license information
 */
@Value
public class License {
    String name;
    @Nullable String url;
    @Nullable String distribution;
    @Nullable String comments;
}

/**
 * Represents Maven prerequisites (like minimum Maven version)
 */
@Value
public class Prerequisites {
    @Nullable String maven;      // Minimum Maven version required
}

/**
 * Represents Maven build profiles
 */
@Value
public class Profile {
    String id;
    @Nullable ProfileActivation activation;
    List<Dependency> dependencies;
    List<ManagedDependency> dependencyManagement;
    List<Plugin> plugins;
    Map<String, String> properties;
    List<MavenRepository> repositories;
}

/**
 * Profile activation conditions
 */
@Value  
public class ProfileActivation {
    boolean activeByDefault;
    @Nullable String jdk;        // JDK version requirement
    @Nullable String os;         // OS requirement
    @Nullable String property;   // System property requirement
    @Nullable String file;       // File existence requirement
}

/**
 * Base interface for Maven element attributes
 */
public interface Attribute extends Serializable {
    // Marker interface for attributes
}

/**
 * Interface for elements that can have attributes
 */
public interface Attributed {
    /**
     * Get all attributes attached to this element
     */
    List<Attribute> getAttributes();
    
    /**
     * Add an attribute to this element
     */
    <T extends Attributed> T withAttributes(List<Attribute> attributes);
}

// Working with the complete data model
ResolvedPom resolvedPom = result.getPom();
Pom pom = resolvedPom.getPom();

// Access project metadata
String projectGroupId = pom.getGroupId();
String projectArtifactId = pom.getArtifactId(); 
String projectVersion = pom.getVersion();
Parent parent = pom.getParent();
Map<String, String> properties = resolvedPom.getProperties();

// Work with dependencies by scope
Map<Scope, List<ResolvedDependency>> dependenciesByScope = result.getDependencies();
List<ResolvedDependency> testDeps = dependenciesByScope.get(Scope.Test);
if (testDeps != null) {
    for (ResolvedDependency dep : testDeps) {
        System.out.println("Test dependency: " + dep.getGroupId() + ":" + dep.getArtifactId() + ":" + dep.getVersion());
    }
}

// Access repositories
List<MavenRepository> repos = resolvedPom.getRepositories();
for (MavenRepository repo : repos) {
    if (repo.acceptsSnapshots()) {
        System.out.println("Snapshot repository: " + repo.getUri());
    }
}