kanon-cli 3.1.0__tar.gz → 3.1.1__tar.gz

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/CHANGELOG.md

@@ -2,8 +2,42 @@
 
 
 
+## v3.1.1 (2026-06-27)
+
+### Fix
+
+* fix: outdated handles namespaced/bare exact tags; why disambiguates same-URL sources (#87)
+
+Two defects found during QA of 3.1.0 against the namespaced/bare catalog.
+
+outdated (closes #85): _normalize_tag_revision_to_constraint only normalised a
+bare refs/tags/<pep440> to ==<pep440>; for a namespaced refs/tags/<path>/<pep440>
+it tried to parse the whole remainder as a Version, failed, and left the ref
+unchanged, so _resolve_constraint_from_tags raised "invalid version constraint".
+It now rewrites only the terminal version component while preserving the
+namespace path, so kanon outdated works for the default exact-tag add of both
+namespaced and bare entries.
+
+why (closes #86): when several sources resolve from the same repo URL at
+different commits (now a supported config), the ambiguity message printed N
+identical "source URL: <url>" tokens, so the operator could not disambiguate.
+_identity_token now returns the source alias (its derive_source_name identity)
+for a URL match on a source node, labelled "source name" -- the tokens are
+distinct and round-trip through the existing source-name grammar
+(kanon why <alias>). Project URL matches are unchanged.
+
+Adds unit + integration coverage for both (namespaced/bare exact-tag outdated;
+distinct alias tokens + alias round-trip for why).
+
+Co-authored-by: t <t@e.x> ([`0d45f67`](https://github.com/caylent-solutions/kanon/commit/0d45f673243861b0aaef823f6d95e0a548c447d4))
+
+
 ## v3.1.0 (2026-06-27)
 
+### Chore
+
+* chore(release): 3.1.0 ([`e62453e`](https://github.com/caylent-solutions/kanon/commit/e62453e4afa86dca403eef43f71b5ceb5e0a115b))
+
 ### Feature
 
 * feat: resolve catalog entries by tag namespace and accept bare project revisions #83
@@ -58,6 +92,12 @@ PEP 440 tag (refs/tags/<pep440>) for single-purpose repos, for both
   CLAUDE_MARKETPLACES_DIR header.
 - Tests, docs, and the kanon-add help snapshot updated. ([`7ed332c`](https://github.com/caylent-solutions/kanon/commit/7ed332c859e69cfd6635035a05c15c03339fdcd1))
 
+### Unknown
+
+* Merge pull request #84 from caylent-solutions/release-3.1.0
+
+Release 3.1.0 ([`fddb0aa`](https://github.com/caylent-solutions/kanon/commit/fddb0aa2ab847ffcf4857384d7e8b40504d1bf91))
+
 
 ## v3.0.0 (2026-06-26)
 

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.1.0
+Version: 3.1.1
 Summary: Kanon (Kanon Package Manager) CLI tool
 Project-URL: Homepage, https://github.com/caylent-solutions/kanon
 Project-URL: Issues, https://github.com/caylent-solutions/kanon/issues

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kanon-cli"
-version = "3.1.0"
+version = "3.1.1"
 description = "Kanon (Kanon Package Manager) CLI tool"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -41,6 +41,7 @@ Issues = "https://github.com/caylent-solutions/kanon/issues"
 
 
 
+
 [tool.hatch.build.targets.wheel]
 packages = [
     "src/kanon_cli",
@@ -136,6 +137,7 @@ enabled = false
 siblings_only = true
 
 
+
 [dependency-groups]
 dev = [
     "build>=1.4.3",

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/src/kanon_cli/__init__.py

@@ -1,3 +1,3 @@
 """Kanon CLI -- Kanon Package Manager."""
 
-__version__ = "3.1.0"
+__version__ = "3.1.1"

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/src/kanon_cli/commands/outdated.py

@@ -155,17 +155,20 @@ def _normalize_revision_for_constraint(rev: str) -> tuple[str | None, str]:
 
 
 def _normalize_tag_revision_to_constraint(revision: str) -> str:
-    """Convert a bare refs/tags/<version> REVISION to a PEP 440 exact-match constraint.
+    """Convert an exact ``refs/tags/...`` REVISION to a PEP 440 exact-match constraint.
 
-    When ``kanon add foo@==1.0.0`` writes ``refs/tags/1.0.0`` as the REVISION,
-    ``_resolve_constraint_from_tags`` cannot evaluate it because the last path
-    component ``1.0.0`` is a bare version, not a PEP 440 specifier. This helper
-    converts ``refs/tags/1.0.0`` to ``refs/tags/==1.0.0`` so the specifier
-    evaluation succeeds (DEFECT-007 fix).
+    When ``kanon add`` pins a source to an exact tag it writes the resolved ref as
+    the REVISION -- a bare ``refs/tags/<version>`` (single-purpose repo) or a
+    namespaced ``refs/tags/<path>/<version>`` (mono repo). ``_resolve_constraint_from_tags``
+    cannot evaluate that directly because the terminal ``<version>`` component is a
+    bare version, not a PEP 440 specifier. This helper rewrites the terminal
+    component to an exact-match specifier (``==<version>``) while preserving any
+    namespace path, so the specifier evaluation succeeds for both forms (DEFECT-007;
+    namespaced/bare exact-tag fix for caylent-solutions/kanon#85).
 
-    Only the ``refs/tags/`` prefix form is relevant here; other forms (plain
-    constraints like ``~=1.0.0``, prefixed constraints like
-    ``refs/tags/prefix/~=1.0.0``) are left unchanged.
+    Only an exact terminal version is rewritten; other forms (plain constraints
+    like ``~=1.0.0``, prefixed constraints like ``refs/tags/prefix/~=1.0.0``, and
+    wildcards like ``refs/tags/prefix/*``) are left unchanged.
 
     Args:
         revision: The REVISION string for a TAG-classified source.
@@ -178,14 +181,17 @@ def _normalize_tag_revision_to_constraint(revision: str) -> str:
     if not revision.startswith(REVISION_REF_PREFIX_TAGS):
         return revision
 
-    bare = revision[len(REVISION_REF_PREFIX_TAGS) :]
+    remainder = revision[len(REVISION_REF_PREFIX_TAGS) :]
+    namespace, _, last = remainder.rpartition("/")
 
     try:
-        Version(bare)
-        return REVISION_REF_PREFIX_TAGS + "==" + bare
+        Version(last)
     except InvalidVersion:
         return revision
 
+    prefix = REVISION_REF_PREFIX_TAGS + (namespace + "/" if namespace else "")
+    return prefix + "==" + last
+
 
 @dataclass
 class OutdatedRow:

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/src/kanon_cli/commands/why.py

@@ -996,16 +996,24 @@ class _ResolvedIdentity:
 
 
 def _identity_token(hit: _MatchHit) -> str:
-    """Return the canonical token to display for a matched identity.
-
-    The token is the user-facing canonical form of what matched: the canonical
-    project URL or source URL, the exact XML manifest path, or the include/source
-    name. It is derived from the matched node, never from the raw argument.
+    """Return the canonical, re-passable token to display for a matched identity.
+
+    The token is the user-facing canonical form of what matched and must be a
+    valid ``kanon why`` argument that resolves back to this one identity (it is
+    what the ambiguity message tells the operator to "pass one of"). For a
+    project URL match it is the canonical project URL; for an XML-path match the
+    exact manifest path; for an include/source-name match the name. For a
+    URL match on a SOURCE node it is the source ALIAS (its
+    ``derive_source_name`` identity), NOT the repository URL: several sources may
+    share one URL at different commits, so the URL is not distinct between them,
+    while the alias is -- and it round-trips through the source-name grammar
+    (caylent-solutions/kanon#86). It is derived from the matched node, never from
+    the raw argument.
     """
     node = hit.node
     if hit.category == "url":
         if node.kind == "source":
-            return node.url or ""
+            return derive_source_name(node.name, warn=False)
         return node.canonical_url or ""
     if hit.category == "xml_path":
         return node.ref or ""
@@ -1015,7 +1023,7 @@ def _identity_token(hit: _MatchHit) -> str:
 def _identity_label(hit: _MatchHit) -> str:
     """Return the human-readable interpretation label for the ambiguity message."""
     if hit.category == "url":
-        return "source URL" if hit.node.kind == "source" else "project URL"
+        return "source name" if hit.node.kind == "source" else "project URL"
     if hit.category == "xml_path":
         return "XML manifest path"
     if hit.category == "source_name":

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/tests/integration/test_outdated_refs_tags_revision_parsing.py

@@ -168,3 +168,55 @@ class TestOutdatedRefsTagsParsing:
                 f"branch revision {revision!r}.\n"
                 f"stdout: {outdated_result.stdout!r}"
             )
+
+    def test_outdated_accepts_namespaced_exact_tag_revision(self, tmp_path: pathlib.Path) -> None:
+        """kanon outdated handles a namespaced exact-tag REVISION (refs/tags/<name>/<ver>).
+
+        Regression for caylent-solutions/kanon#85: ``kanon add foo`` against a
+        catalog whose tags are namespaced (``foo/1.0.0``) writes
+        ``KANON_SOURCE_FOO_REF=refs/tags/foo/1.0.0``; outdated previously raised
+        ``invalid version constraint '1.0.0'`` because the namespaced exact tag
+        was not normalised to ``==``. Now it resolves and reports the available
+        upgrade to ``1.1.0``.
+        """
+        bare = _create_manifest_repo_with_tags(
+            tmp_path / "catalog",
+            entry_names=["foo"],
+            tags=["foo/1.0.0", "foo/1.1.0"],
+        )
+        catalog_source = f"file://{bare}@main"
+
+        workspace = tmp_path / "workspace"
+        workspace.mkdir()
+
+        add_result = _run_kanon(
+            ["add", "foo@==1.0.0", "--catalog-source", catalog_source],
+            cwd=workspace,
+        )
+        assert add_result.returncode == 0, (
+            f"kanon add setup failed (expected 0, got {add_result.returncode}).\n"
+            f"stdout: {add_result.stdout!r}\nstderr: {add_result.stderr!r}"
+        )
+        kanon_text = (workspace / ".kanon").read_text(encoding="utf-8")
+        assert "refs/tags/foo/1.0.0" in kanon_text, f"expected the namespaced exact tag in .kanon; got:\n{kanon_text}"
+
+        env = dict(os.environ)
+        env.pop("KANON_CATALOG_SOURCES", None)
+        outdated_result = subprocess.run(
+            [sys.executable, "-m", "kanon_cli", "outdated", "--catalog-source", catalog_source],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=str(workspace),
+        )
+
+        assert outdated_result.returncode == 0, (
+            f"Expected exit 0 for namespaced exact tag, got {outdated_result.returncode}.\n"
+            f"stdout: {outdated_result.stdout!r}\nstderr: {outdated_result.stderr!r}"
+        )
+        assert "invalid version constraint" not in outdated_result.stderr, (
+            f"outdated still raises the constraint error.\nstderr: {outdated_result.stderr!r}"
+        )
+        assert "1.0.0" in outdated_result.stdout and "1.1.0" in outdated_result.stdout, (
+            f"Expected current 1.0.0 and latest 1.1.0 in the outdated table.\nstdout: {outdated_result.stdout!r}"
+        )

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/tests/integration/test_why_ambiguous.py

@@ -443,3 +443,37 @@ class TestWhyMultiplicityAndIncludeName:
         assert "matched include_name 'remote'" in result.stdout
         chain_lines = [line for line in result.stdout.splitlines() if include_path in line and " -> " in line]
         assert len(chain_lines) == 3, f"expected 3 chains, got: {result.stdout!r}"
+
+    def test_same_url_sources_print_distinct_alias_tokens_and_round_trip(self, tmp_path: pathlib.Path) -> None:
+        """Querying a URL shared by several sources prints DISTINCT, re-passable alias tokens.
+
+        Regression for caylent-solutions/kanon#86: when multiple sources resolve
+        from the same repo URL at different commits (now a supported config), the
+        old ambiguity message printed N identical `source URL: <url>` lines, so
+        the operator could not disambiguate. The tokens are now the distinct
+        source aliases under a `source name` label, and re-passing one alias
+        resolves to exactly that source.
+        """
+        include_path = "repo-specs/git-connection/remote.xml"
+        kanon_file = _make_minimal_kanon_file(tmp_path, "src0")
+        lock_file = _write_multi_source_lockfile(tmp_path, 3, "remote", include_path)
+
+        ambiguous = _run_why(kanon_file, lock_file, "https://github.com/org/catalog")
+        assert ambiguous.returncode != 0, f"expected ambiguity exit; stdout: {ambiguous.stdout!r}"
+        assert "is ambiguous" in ambiguous.stderr
+        assert "source name" in ambiguous.stderr
+        assert "source URL" not in ambiguous.stderr
+
+        token_lines = [
+            line.strip() for line in ambiguous.stderr.splitlines() if line.strip().startswith("source name:")
+        ]
+        tokens = sorted(line.split(":", 1)[1].strip() for line in token_lines)
+        assert tokens == ["src0", "src1", "src2"], (
+            f"disambiguation tokens must be the distinct aliases, got: {tokens!r}\nstderr: {ambiguous.stderr!r}"
+        )
+
+        resolved = _run_why(kanon_file, lock_file, "src1")
+        assert resolved.returncode == 0, (
+            f"re-passing the alias 'src1' must resolve to exactly one source.\nstderr: {resolved.stderr!r}"
+        )
+        assert "src1" in resolved.stdout

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/tests/unit/test_constants_outdated_refs_tags.py

@@ -194,6 +194,14 @@ class TestNormalizeTagRevisionToConstraint:
             ("refs/tags/*", "refs/tags/*"),
             ("~=1.0.0", "~=1.0.0"),
             (">=1.0.0", ">=1.0.0"),
+            ("refs/tags/history/0.1.1", "refs/tags/history/==0.1.1"),
+            ("refs/tags/0.1.0", "refs/tags/==0.1.0"),
+            ("refs/tags/a/b/c/2.3.4", "refs/tags/a/b/c/==2.3.4"),
+            ("refs/tags/history/1.0.0a1", "refs/tags/history/==1.0.0a1"),
+            ("refs/tags/history/~=0.1.0", "refs/tags/history/~=0.1.0"),
+            ("refs/tags/history/>=1.0.0,<2.0.0", "refs/tags/history/>=1.0.0,<2.0.0"),
+            ("refs/tags/history/*", "refs/tags/history/*"),
+            ("refs/tags/builders-plugins/0.1.2", "refs/tags/builders-plugins/==0.1.2"),
         ],
     )
     def test_normalize_tag_revision(self, revision: str, expected: str) -> None:

{kanon_cli-3.1.0 → kanon_cli-3.1.1}/tests/unit/test_why_ambiguity.py

@@ -812,3 +812,36 @@ class TestMultiplicityNotAmbiguity:
         assert "ambiguous" in captured.err.lower()
         assert "source name" in captured.err.lower()
         assert "include name" in captured.err.lower()
+
+
+@pytest.mark.unit
+class TestIdentityTokenForSources:
+    """A URL match on a source yields its alias (distinct, re-passable), not the shared URL (#86)."""
+
+    def test_url_matched_source_token_is_alias_with_source_name_label(self) -> None:
+        from kanon_cli.commands.why import _MatchHit, _identity_label, _identity_token
+        from kanon_cli.core.metadata import derive_source_name
+
+        node = _make_source_node(name="builders_plugins", url="https://github.com/org/catalog")
+        hit = _MatchHit(category="url", label="x", node=node)
+        assert _identity_token(hit) == derive_source_name("builders_plugins", warn=False)
+        assert _identity_token(hit) != node.url
+        assert _identity_label(hit) == "source name"
+
+    def test_same_url_distinct_aliases_yield_distinct_tokens(self) -> None:
+        from kanon_cli.commands.why import _MatchHit, _identity_token
+
+        url = "https://github.com/org/catalog"
+        tokens = {
+            _identity_token(_MatchHit(category="url", label="x", node=_make_source_node(name=alias, url=url)))
+            for alias in ("src0", "src1", "src2")
+        }
+        assert tokens == {"src0", "src1", "src2"}
+
+    def test_url_matched_project_token_stays_canonical_url(self) -> None:
+        from kanon_cli.commands.why import _MatchHit, _identity_label, _identity_token
+
+        node = _make_project_node(name="proj", url="https://github.com/org/proj")
+        hit = _MatchHit(category="url", label="x", node=node)
+        assert _identity_token(hit) == node.canonical_url
+        assert _identity_label(hit) == "project URL"