Unify endpoint handling around list[Dependency]

The resolver API, POM generation, environment builder, and CLI commands
all previously operated on parallel lists of Components and Coordinates,
with BOM management controlled via separate managed/boms parameters and
a _current_boms side-channel on the builder. This made it impossible to
preserve classifier, packaging, and scope through the pipeline, and
split the "is this dependency raw?" concern across multiple call sites.

Now Dependency is the primary downstream currency everywhere:

- Add raw: bool to Dependency so BOMs can be computed from Dependencies
  alone (_compute_boms replaces _resolve_boms + filter_managed_components)
- Resolver.resolve/get_dependency_list/get_dependency_tree accept
  list[Dependency] and compute BOMs internally; drop managed/boms params
- generate_pom_xml accepts list[Dependency] and emits classifier, type,
  and scope elements when non-default
- EnvironmentBuilder.from_endpoint uses _coordinates_to_dependencies
  directly instead of routing through from_components
- _build_environment accepts list[Dependency]; remove _current_boms
- Remove from_components, _parse_endpoint, _components_to_dependencies,
  filter_managed_components, _resolve_boms, _listify

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: ctrueden

BUGS.txt

@@ -13,8 +13,6 @@ Add py.typed file to package root for static type analyzers
 Use https://github.com/ross/requests-futures
 to do asynchronous parallel downloads of Maven artifacts?
 
-Endpoints consist of Components right now -- this is wrong, it needs to be Artifacts/Dependencies -- because you should be able to mix in GACPVs with non-default classifier and/or packaging! (Well, packaging is arguable...)
-
 Remove or repurpose obsolete files in docs/
 
 Decide about remaining `~/.jgorc` references throughout the codebase

docs/migration-example.md

@@ -30,10 +30,8 @@ from jgo.exec import JavaRunner
 
 # Full control over each step
 maven = MavenContext()
-component = maven.project('org.python', 'jython-standalone').at_version('RELEASE')
-
 builder = EnvironmentBuilder(context=maven)
-environment = builder.from_components([component])
+environment = builder.from_endpoint("org.python:jython-standalone:RELEASE")
 
 runner = JavaRunner()
 result = runner.run(environment)
@@ -379,7 +377,9 @@ def build_analysis_environment():
         link_strategy=LinkStrategy.HARD
     )
 
-    environment = builder.from_components(components)
+    environment = builder.from_endpoint(
+        "+".join(f"{c.groupId}:{c.artifactId}:{c.version}" for c in components)
+    )
 
     return environment
 

docs/migration.md

@@ -229,7 +229,7 @@ component = maven.project("org.python", "jython-standalone").at_version("2.7.3")
 
 # Layer 2: Environment materialization
 builder = EnvironmentBuilder(context=maven)
-env = builder.from_components([component])
+env = builder.from_endpoint("org.python:jython-standalone:2.7.3")
 
 # Layer 3: Execution
 runner = JavaRunner()

docs/terminology.md

@@ -69,7 +69,7 @@ print(env.main_class) # org.python.util.jython
 
 **Methods:**
 - `from_endpoint(endpoint: str)` - Build from endpoint string (e.g., "G:A:V")
-- `from_components(components: list[Component])` - Build from Component objects
+- `from_spec(spec: EnvironmentSpec)` - Build from a jgo.toml specification
 
 **Usage:**
 ```python

src/jgo/__init__.py

@@ -60,7 +60,7 @@
 >>>
 >>> # Layer 2: Environment materialization
 >>> builder = EnvironmentBuilder(context=maven, link_strategy=LinkStrategy.HARD)
->>> environment = builder.from_components([component])
+>>> environment = builder.from_endpoint("org.python:jython-standalone:2.7.3")
 >>>
 >>> # Layer 3: Execution
 >>> runner = JavaRunner(jvm_config=JVMConfig(max_heap="2G"))

src/jgo/cli/commands/info.py

@@ -11,9 +11,9 @@
 
 from ...config import GlobalSettings
 from ...env import EnvironmentSpec
-from ...env.builder import filter_managed_components
 from ...env.jar import parse_manifest, read_raw_manifest
 from ...parse.coordinate import Coordinate
+from ...parse.endpoint import Endpoint
 from ...styles import COORD_HELP_FULL
 from ..args import build_parsed_args
 from ..console import console_print
@@ -431,28 +431,23 @@ def _print_deps(ctx, endpoint, list_mode: bool):
     context = create_maven_context(args, config.to_dict())
     builder = create_environment_builder(args, config.to_dict(), context)
 
-    # Parse coordinates into components
+    # Parse coordinates into dependencies
     if args.is_spec_mode():
         spec_file = args.get_spec_file()
         if not spec_file.exists():
             _log.error(f"{spec_file} not found")
             ctx.exit(1)
         spec = EnvironmentSpec.load(spec_file)
-        components = []
-        for coord_str in spec.coordinates:
-            coord = _parse_coord_or_die(ctx, coord_str)
-            version = coord.version or "RELEASE"
-            component = context.project(coord.groupId, coord.artifactId).at_version(
-                version
-            )
-            components.append(component)
-        boms = None  # No BOM management for spec mode
+        coordinates = [
+            Coordinate.parse(coord_str) for coord_str in spec.coordinates
+        ]
+        dependencies = builder._coordinates_to_dependencies(coordinates)
     else:
         if not endpoint:
             _log.error("No endpoint specified")
             ctx.exit(1)
-        components, coordinates, _ = builder._parse_endpoint(endpoint)
-        boms = filter_managed_components(components, coordinates)
+        parsed = Endpoint.parse(endpoint)
+        dependencies = builder._coordinates_to_dependencies(parsed.coordinates)
 
-    print_dependencies(components, context, boms=boms, list_mode=list_mode)
+    print_dependencies(dependencies, context, list_mode=list_mode)
     ctx.exit(0)

src/jgo/cli/commands/list.py

@@ -9,8 +9,8 @@
 
 from ...config import GlobalSettings
 from ...env import EnvironmentSpec
-from ...env.builder import filter_managed_components
 from ...parse.coordinate import Coordinate
+from ...parse.endpoint import Endpoint
 from ..args import build_parsed_args
 from ..context import create_environment_builder, create_maven_context
 from ..output import print_dependencies
@@ -58,33 +58,25 @@ def execute(args: ParsedArgs, config: dict) -> int:
     context = create_maven_context(args, config)
     builder = create_environment_builder(args, config, context)
 
-    # Parse coordinates into components
+    # Parse coordinates into dependencies
     if args.is_spec_mode():
         spec_file = args.get_spec_file()
         if not spec_file.exists():
             _log.error(f"{spec_file} not found")
             return 1
         spec = EnvironmentSpec.load(spec_file)
-        components = []
-        for coord_str in spec.coordinates:
-            coord = Coordinate.parse(coord_str)
-            version = coord.version or "RELEASE"
-            component = context.project(coord.groupId, coord.artifactId).at_version(
-                version
-            )
-            components.append(component)
-        boms = None
+        coordinates = [Coordinate.parse(coord_str) for coord_str in spec.coordinates]
+        dependencies = builder._coordinates_to_dependencies(coordinates)
     else:
         if not args.endpoint:
             _log.error("No endpoint specified")
             return 1
-        components, coordinates, _ = builder._parse_endpoint(args.endpoint)
-        boms = filter_managed_components(components, coordinates)
+        parsed = Endpoint.parse(args.endpoint)
+        dependencies = builder._coordinates_to_dependencies(parsed.coordinates)
 
     print_dependencies(
-        components,
+        dependencies,
         context,
-        boms=boms,
         list_mode=True,
         direct_only=args.direct_only,
         optional_depth=args.get_effective_optional_depth(),

src/jgo/cli/commands/tree.py

@@ -9,8 +9,8 @@
 
 from ...config import GlobalSettings
 from ...env import EnvironmentSpec
-from ...env.builder import filter_managed_components
 from ...parse.coordinate import Coordinate
+from ...parse.endpoint import Endpoint
 from ..args import build_parsed_args
 from ..context import create_environment_builder, create_maven_context
 from ..output import print_dependencies
@@ -56,33 +56,25 @@ def execute(args: ParsedArgs, config: dict) -> int:
     context = create_maven_context(args, config)
     builder = create_environment_builder(args, config, context)
 
-    # Parse coordinates into components
+    # Parse coordinates into dependencies
     if args.is_spec_mode():
         spec_file = args.get_spec_file()
         if not spec_file.exists():
             _log.error(f"{spec_file} not found")
             return 1
         spec = EnvironmentSpec.load(spec_file)
-        components = []
-        for coord_str in spec.coordinates:
-            coord = Coordinate.parse(coord_str)
-            version = coord.version or "RELEASE"
-            component = context.project(coord.groupId, coord.artifactId).at_version(
-                version
-            )
-            components.append(component)
-        boms = None
+        coordinates = [Coordinate.parse(coord_str) for coord_str in spec.coordinates]
+        dependencies = builder._coordinates_to_dependencies(coordinates)
     else:
         if not args.endpoint:
             _log.error("No endpoint specified")
             return 1
-        components, coordinates, _ = builder._parse_endpoint(args.endpoint)
-        boms = filter_managed_components(components, coordinates)
+        parsed = Endpoint.parse(args.endpoint)
+        dependencies = builder._coordinates_to_dependencies(parsed.coordinates)
 
     print_dependencies(
-        components,
+        dependencies,
         context,
-        boms=boms,
         list_mode=False,
         optional_depth=args.get_effective_optional_depth(),
     )

src/jgo/cli/output.py

@@ -24,7 +24,7 @@
 if TYPE_CHECKING:
     from ..env import Environment
     from ..maven import MavenContext
-    from ..maven.core import Component
+    from ..maven.core import Dependency
     from .args import ParsedArgs
 
 
@@ -175,20 +175,18 @@ def print_main_classes(environment: Environment) -> None:
 
 
 def print_dependencies(
-    components: list[Component],
+    dependencies: list[Dependency],
     context: MavenContext,
-    boms: list[Component] | None = None,
     list_mode: bool = False,
     direct_only: bool = False,
     optional_depth: int = 0,
 ) -> None:
     """
-    Print dependencies for the given components.
+    Print dependencies for the given input dependencies.
 
     Args:
-        components: List of components to print dependencies for
+        dependencies: List of input dependencies to print
         context: Maven context containing the resolver
-        boms: List of components to use as managed BOMs (None = none managed)
         list_mode: If True, print flat list (like mvn dependency:list).
                   If False, print tree (like mvn dependency:tree).
         direct_only: If True and list_mode is True, show only direct dependencies
@@ -203,9 +201,7 @@ def print_dependencies(
 
         # Get the dependency list
         root, deps = context.resolver.get_dependency_list(
-            components,
-            managed=bool(boms),
-            boms=boms,
+            dependencies,
             transitive=not direct_only,
             optional_depth=optional_depth,
         )
@@ -220,9 +216,7 @@ def print_dependencies(
 
         # Get the dependency tree
         tree = context.resolver.get_dependency_tree(
-            components,
-            managed=bool(boms),
-            boms=boms,
+            dependencies,
             optional_depth=optional_depth,
         )