Add explicit positioning for coordinate parsing

ctrueden · claude · ctrueden · commit 48e60b79653e · 2026-01-02T21:42:27.000-06:00
Implement strict mode parsing that uses empty strings (consecutive colons) to disambiguate coordinate components, avoiding heuristic ambiguity. When empty strings are detected (e.g., g:a::c), the parser switches to strict positional format: G:A:V:C:P:S (groupId, artifactId, version, classifier, packaging, scope). Examples: - org.example:my-lib:1.0.0: → version=1.0.0, classifier=None (explicit) - org.example:my-lib::sources → version=None, classifier=sources - org.example:my-lib:1.0::pom → version=1.0, packaging=pom, skip classifier Features: - Maintains backward compatibility (heuristics still work without empty strings) - Validates scope values in strict mode - Works with existing features (raw flag !, placement suffixes) Changes: - src/jgo/parse/coordinate.py: Added strict mode parsing logic - tests/test_coordinate.py: Added 15 comprehensive test cases - README.md: Documented explicit positioning syntax 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -181,6 +181,15 @@ Endpoint Format:
   Specify main class: org.scijava:scijava-common@ScriptREPL
   Auto-completion: Use simple class name (e.g., @ScriptREPL) and it will be auto-completed
 
+Explicit Positioning (Advanced):
+  Use empty strings (consecutive colons) to avoid heuristic parsing:
+  - g:a:1.0:      → version=1.0, classifier=None (explicit)
+  - g:a::sources  → version=None, classifier=sources (explicit)
+  - g:a:v::jar    → version=v, packaging=jar, skip classifier
+
+  Format: groupId:artifactId:version:classifier:packaging:scope
+  Empty positions default to None. Useful when heuristics fail.
+
 Full documentation: jgo --help
 ```
 
diff --git a/src/jgo/parse/coordinate.py b/src/jgo/parse/coordinate.py
@@ -12,6 +12,17 @@
 - G:A:P:C:V:S (full format with scope)
 - Other orderings of these - see the Coordinate.parse function for details
 
+Explicit Positioning (Strict Mode):
+To avoid heuristic ambiguity, use empty strings (consecutive colons) to specify
+exact positions. When empty strings are detected, the parser uses strict positional
+format: G:A:V:C:P:S
+
+Examples:
+- "org.example:my-lib:1.0.0:"      → version=1.0.0, classifier=None (explicit)
+- "org.example:my-lib::sources"    → version=None, classifier=sources (explicit)
+- "org.example:my-lib:1.0::pom"    → version=1.0, packaging=pom (skip classifier)
+- "junit:junit:4.13:::test"        → version=4.13, scope=test (skip C and P)
+
 The Coordinate class is a simple data structure for holding parsed coordinate
 components. It does not perform Maven resolution, version interpolation, or
 dependency management - for that, see the jgo.maven subpackage.
@@ -296,6 +307,11 @@ def _parse_coordinate_dict(coordinate: str) -> dict[str, str | None | bool]:
 
     This is the internal implementation that returns a dict.
     External callers should use Coordinate.parse() instead.
+
+    Supports two modes:
+    1. Heuristic mode (default): Uses pattern matching to infer component types
+    2. Strict mode: When empty strings are present (e.g., "g:a::c"), uses
+       fixed positions G:A:V:C:P:S to avoid ambiguity
     """
     # Check for raw/unmanaged flag (! or \! suffix) on the entire coordinate
     # Handle both ! and \! (shell escaped) before splitting
@@ -329,6 +345,9 @@ def _parse_coordinate_dict(coordinate: str) -> dict[str, str | None | bool]:
             "Invalid coordinate string: must have at least groupId and artifactId"
         )
 
+    # Check if we're in strict mode (empty strings present, indicating explicit positions)
+    has_empty_strings = any(part == "" for part in parts[2:])  # Skip G and A positions
+
     # Handle " (optional)" suffix early - it's typically attached to the last part
     optional = False
     if parts[-1].endswith(" (optional)"):
@@ -363,6 +382,43 @@ def _parse_coordinate_dict(coordinate: str) -> dict[str, str | None | bool]:
 
     num_parts = len(parts)
 
+    # STRICT MODE: When empty strings are present, use fixed positions G:A:V:C:P:S
+    # This allows explicit disambiguation without relying on heuristics
+    if has_empty_strings:
+        if num_parts >= 3:
+            version = parts[2] if parts[2] else None
+        if num_parts >= 4:
+            classifier = parts[3] if parts[3] else None
+        if num_parts >= 5:
+            packaging = parts[4] if parts[4] else None
+        if num_parts >= 6:
+            scope = parts[5] if parts[5] else None
+        if num_parts >= 7:
+            # More than 6 positions (G:A:V:C:P:S) is an error
+            raise ValueError(
+                f"Too many parts in strict mode coordinate: {coordinate}. "
+                "Expected at most G:A:V:C:P:S (6 positions total)."
+            )
+
+        # In strict mode, validate that scope is actually a scope if provided
+        if scope and scope not in scope_values:
+            raise ValueError(
+                f"Invalid scope '{scope}' in strict mode. "
+                f"Must be one of: {', '.join(sorted(scope_values))}"
+            )
+
+        return {
+            "groupId": groupId,
+            "artifactId": artifactId,
+            "packaging": packaging,
+            "classifier": classifier,
+            "version": version,
+            "scope": scope,
+            "optional": optional,
+            "raw": raw,
+            "placement": placement,
+        }
+
     if num_parts == 2:
         # G:A - minimal coordinate
         pass
diff --git a/tests/test_coordinate.py b/tests/test_coordinate.py
@@ -374,3 +374,180 @@ def test_roundtrip_with_scope():
     original = "junit:junit:jar:4.13.2:test"
     coord = Coordinate.parse(original)
     assert str(coord) == original
+
+
+# =============================================================================
+# Strict mode tests (explicit positioning with empty strings)
+# =============================================================================
+
+
+def test_strict_mode_version_explicit():
+    """Test G:A:V: format - explicit version, no classifier (strict mode)."""
+    result = Coordinate.parse("org.example:my-artifact:1.2.3:")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-artifact"
+    assert result.version == "1.2.3"
+    assert result.classifier is None
+    assert result.packaging is None
+    assert result.scope is None
+
+
+def test_strict_mode_classifier_without_version():
+    """Test G:A::C format - no version, explicit classifier (strict mode)."""
+    result = Coordinate.parse("org.example:my-lib::sources")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version is None
+    assert result.classifier == "sources"
+    assert result.packaging is None
+
+
+def test_strict_mode_version_and_classifier():
+    """Test G:A:V:C: format - explicit version and classifier (strict mode)."""
+    result = Coordinate.parse("org.lwjgl:lwjgl:3.3.1:natives-linux:")
+    assert result.groupId == "org.lwjgl"
+    assert result.artifactId == "lwjgl"
+    assert result.version == "3.3.1"
+    assert result.classifier == "natives-linux"
+    assert result.packaging is None
+    assert result.scope is None
+
+
+def test_strict_mode_version_skip_classifier_packaging():
+    """Test G:A:V::P format - version and packaging, skip classifier (strict mode)."""
+    result = Coordinate.parse("org.example:my-lib:1.0.0::pom")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version == "1.0.0"
+    assert result.classifier is None
+    assert result.packaging == "pom"
+    assert result.scope is None
+
+
+def test_strict_mode_skip_version_packaging():
+    """Test G:A:::P format - skip version and classifier, specify packaging (strict mode)."""
+    result = Coordinate.parse("org.example:my-webapp:::pom")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-webapp"
+    assert result.version is None
+    assert result.classifier is None
+    assert result.packaging == "pom"
+
+
+def test_strict_mode_full_with_scope():
+    """Test G:A:V:C:P:S format - full strict specification (strict mode)."""
+    # Use empty classifier to trigger strict mode while specifying all positions
+    result = Coordinate.parse("org.example:my-lib:1.2.3::jar:compile")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version == "1.2.3"
+    assert result.classifier is None
+    assert result.packaging == "jar"
+    assert result.scope == "compile"
+
+
+def test_strict_mode_only_scope():
+    """Test G:A::::S format - only scope specified (strict mode)."""
+    result = Coordinate.parse("org.example:my-lib::::test")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version is None
+    assert result.classifier is None
+    assert result.packaging is None
+    assert result.scope == "test"
+
+
+def test_strict_mode_version_and_scope():
+    """Test G:A:V:::S format - version and scope, skip middle parts (strict mode)."""
+    result = Coordinate.parse("junit:junit:4.13.2:::test")
+    assert result.groupId == "junit"
+    assert result.artifactId == "junit"
+    assert result.version == "4.13.2"
+    assert result.classifier is None
+    assert result.packaging is None
+    assert result.scope == "test"
+
+
+def test_strict_mode_invalid_scope():
+    """Test that strict mode validates scope values."""
+    try:
+        Coordinate.parse("org.example:my-lib::::invalid-scope")
+        assert False, "Should have raised ValueError for invalid scope"
+    except ValueError as e:
+        assert "Invalid scope" in str(e)
+        assert "invalid-scope" in str(e)
+
+
+def test_strict_mode_too_many_parts():
+    """Test that strict mode rejects more than 6 positions (7+ parts)."""
+    try:
+        # Need empty string to trigger strict mode, and 7+ parts
+        Coordinate.parse("g:a:v:c:p:s:extra:")
+        assert False, "Should have raised ValueError for too many parts"
+    except ValueError as e:
+        assert "Too many parts" in str(e)
+        assert "at most G:A:V:C:P:S" in str(e)
+
+
+def test_strict_mode_disambiguate_version_vs_classifier():
+    """
+    Test strict mode disambiguates ambiguous cases.
+
+    Without trailing colon, "sources" could be version or classifier (heuristic decides).
+    With trailing colon, position is explicit.
+    """
+    # Heuristic mode: "sources" detected as classifier
+    heuristic = Coordinate.parse("org.example:my-lib:sources")
+    assert heuristic.classifier == "sources"
+    assert heuristic.version is None
+
+    # Strict mode: "sources" in position 2 = version
+    strict = Coordinate.parse("org.example:my-lib:sources:")
+    assert strict.version == "sources"  # Unusual but explicit
+    assert strict.classifier is None
+
+
+def test_strict_mode_disambiguate_packaging_vs_version():
+    """
+    Test strict mode disambiguates packaging vs version.
+
+    "jar" could be packaging (heuristic) or version (if used as version string).
+    """
+    # Heuristic mode: "jar" detected as packaging
+    heuristic = Coordinate.parse("org.example:my-lib:jar")
+    assert heuristic.packaging == "jar"
+    assert heuristic.version is None
+
+    # Strict mode: "jar" in position 2 = version (unusual but explicit)
+    strict = Coordinate.parse("org.example:my-lib:jar:")
+    assert strict.version == "jar"
+    assert strict.packaging is None
+
+
+def test_strict_mode_empty_version_string():
+    """Test G:A:: format - both version and classifier are explicitly empty."""
+    result = Coordinate.parse("org.example:my-lib::")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version is None
+    assert result.classifier is None
+    assert result.packaging is None
+
+
+def test_strict_mode_with_raw_flag():
+    """Test that strict mode works with raw flag (! suffix)."""
+    result = Coordinate.parse("org.example:my-lib:1.0.0:!")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version == "1.0.0"
+    assert result.classifier is None
+    assert result.raw is True
+
+
+def test_strict_mode_preserves_special_versions():
+    """Test that strict mode preserves RELEASE, LATEST, MANAGED versions."""
+    result = Coordinate.parse("org.example:my-lib:RELEASE:")
+    assert result.groupId == "org.example"
+    assert result.artifactId == "my-lib"
+    assert result.version == "RELEASE"
+    assert result.classifier is None
