fix(outdated): fold monorepo tag review follow-ups

Sync the shipped command guide with the new outdated behavior, add integration coverage for marketplace monorepo tag inference, and align automatic outdated tag patterns with the documented double-dash convention. Addresses shepherd panel follow-ups for PR #1504.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

docs/src/content/docs/reference/cli/marketplace.md

@@ -203,8 +203,20 @@ versions available.
 
 When remote tags use a non-default layout (for example `my-pkg_v1.0.1`), set
 `tag_pattern: "{name}_v{version}"` on the package entry or under `build:` in
-`apm.yml`. If no tags match the configured pattern, `apm marketplace outdated`
-tries common layouts (`v{version}`, `{name}_v{version}`, etc.) automatically.
+`apm.yml`:
+
+```yaml
+packages:
+  - name: my-pkg
+    source: org/monorepo
+    version: "^1.0.0"
+    tag_pattern: "{name}_v{version}"
+```
+
+If no tags match the configured pattern, `apm marketplace outdated` tries common
+layouts (`v{version}`, `{name}_v{version}`, `{name}--v{version}`, etc.)
+automatically. Set `tag_pattern` explicitly when your producer uses a different
+layout.
 
 ### `apm marketplace publish`
 

docs/src/content/docs/reference/cli/outdated.md

@@ -17,12 +17,15 @@ apm outdated [OPTIONS]
 
 `apm outdated` reads `apm.lock.yaml` and queries each remote to detect staleness:
 
-- **Tag-pinned deps** (e.g. `v1.2.3`, `1.2.3`, or patterned tags like `my-pkg_v1.2.3`): semver compare against the latest matching remote tag. Patterned tags (`{name}_v{version}`, `{name}-v{version}`, etc.) are detected automatically from the locked ref.
+- **Plain tag-pinned deps** (e.g. `v1.2.3` or `1.2.3`): semver compare against the latest matching remote tag.
+- **Patterned tag-pinned deps** (e.g. `my-pkg_v1.2.3`, `my-pkg--v1.2.3`, or `my-pkg-v1.2.3`): semver compare against the latest tag matching the package-specific pattern inferred from the locked ref.
 - **Branch-pinned deps** (e.g. `main`): compare the locked commit SHA against the remote branch tip.
 - **Default-branch deps** (no ref): compare against `main`/`master` tip.
 - **Marketplace deps**: compare the installed ref against the marketplace entry's current `source.ref`.
 - **Registry deps** (experimental `registries` feature): compare the lockfile's exact `version` against the highest semver on the registry that satisfies the manifest range (same resolution semantics as `apm install`). Manifest ranges come from the root `apm.yml` and from installed packages' `apm.yml` files (transitive deps). When a registry lockfile entry has no manifest range, `apm outdated` compares against the highest published version and labels the source `(lockfile)`.
 
+Common monorepo layouts are detected automatically for `outdated` reporting. Set an explicit marketplace `tag_pattern` when your producer uses a different layout than the built-in patterns.
+
 Local dependencies and Artifactory-hosted deps are skipped. Legacy `apm.lock` files are migrated to `apm.lock.yaml` automatically on read.
 
 To apply the suggested updates, run `apm install --update` (see [Related](#related)).

packages/apm-guide/.apm/skills/apm-usage/commands.md

@@ -19,7 +19,7 @@
 | `apm deps why PKG` | Explain why a package is installed (walks lockfile bottom-up to direct deps; analogue of `npm why` / `yarn why`) | `-g` global, `--json` |
 | `apm find <PATH>` | Trace a deployed file back to the package(s) that contributed it (inverse of install; reads `apm.lock.yaml` only) | `--source` show OCI/git/local origin, `--path` show full why-chain (same as `apm deps why`) |
 | `apm view PKG [FIELD]` | View package details or remote refs | `-g` global, `FIELD=versions` |
-| `apm outdated` | Check locked deps via SHA/semver comparison | `-g` global, `-v` verbose, `-j N` parallel checks |
+| `apm outdated` | Check locked deps via SHA/semver comparison; patterned per-package tags are auto-detected | `-g` global, `-v` verbose, `-j N` parallel checks |
 | `apm deps info PKG` | Alias for `apm view PKG` local metadata | -- |
 | `apm deps clean` | Clean dependency cache | `--dry-run`, `-y` skip confirm |
 | `apm deps update [PKGS...]` | Deprecated -- use `apm update` instead (now a strict superset). Update specific packages | `--verbose`, `--force`, `--target` (comma-separated), `--parallel-downloads N`, `-g/--global`, `--legacy-skill-paths` |
@@ -136,7 +136,7 @@ Credentials resolve via `APM_REGISTRY_TOKEN_{NAME}` env var (or `apm config set
 |---------|---------|-----------|
 | `apm marketplace init` | Append a `marketplace:` block to `apm.yml` and create `.claude-plugin/` | `--force`, `--no-gitignore-check`, `--name`, `--owner` |
 | `apm marketplace migrate` | Fold a legacy `marketplace.yml` into `apm.yml`'s `marketplace:` block; deletes `marketplace.yml` on success | `--force`/`--yes`/`-y`, `--dry-run`, `-v` |
-| `apm marketplace outdated` | Report upgradable plugins, range-aware | `--offline`, `--include-prerelease`, `-v` |
+| `apm marketplace outdated` | Report upgradable plugins, range-aware; respects `tag_pattern` and common monorepo tag layouts | `--offline`, `--include-prerelease`, `-v` |
 | `apm marketplace check` | Validate the `marketplace:` block and verify refs resolve | `--offline`, `-v` |
 | `apm marketplace doctor` | Diagnose git, network, auth, marketplace config readiness, and (when a `marketplace:` block is present) **format coverage** -- which output profiles are configured vs. supported, so producers can spot easy reach wins (e.g. add `codex: {}` to also publish for Codex consumers). All marketplace-specific rows are informational and never affect exit code. | `-v` |
 | `apm marketplace publish` | Open PRs on consumer repos from `consumer-targets.yml` | `--targets PATH`, `--dry-run`, `--no-pr`, `--draft`, `--allow-downgrade`, `--allow-ref-change`, `--parallel N`, `-y` |

src/apm_cli/commands/marketplace/__init__.py

@@ -8,6 +8,7 @@
 
 import builtins
 import json
+import logging
 import re
 import sys
 import traceback
@@ -49,6 +50,8 @@
 from ...utils.path_security import PathTraversalError, validate_path_segments
 from .._helpers import _get_console, _is_interactive
 
+logger = logging.getLogger(__name__)
+
 # Restore builtins shadowed by subcommand names
 list = builtins.list
 
@@ -1048,6 +1051,12 @@ def _collect(pattern: str) -> list:
     if not results:
         inferred = infer_tag_pattern_from_refs(refs, entry.name)
         if inferred and inferred != pattern:
+            logger.debug(
+                "Configured tag pattern %r matched no tags for %s; inferred %r",
+                pattern,
+                entry.name,
+                inferred,
+            )
             results = _collect(inferred)
     return results
 

src/apm_cli/commands/outdated.py

@@ -16,6 +16,7 @@
 
 logger = logging.getLogger(__name__)
 
+# Fallback heuristic for _resolve_tag_pattern when inference misses plain tags.
 TAG_RE = re.compile(r"^v?\d+\.\d+\.\d+")
 
 
@@ -47,6 +48,12 @@ def _resolve_tag_pattern(current_ref: str, package_name: str) -> str | None:
 
     inferred = infer_tag_pattern(current_ref, package_name)
     if inferred:
+        logger.debug(
+            "Resolved tag pattern %r for %s from ref %s",
+            inferred,
+            package_name,
+            current_ref,
+        )
         return inferred
     if TAG_RE.match(current_ref or ""):
         return "v{version}" if (current_ref or "").startswith("v") else "{version}"
@@ -264,11 +271,11 @@ def _check_one_dep(dep, downloader, verbose, registry_ctx=None):
             )
 
         _, latest_tag = candidates[0]
-        current_ver = (
-            parse_tag_version(current_ref, tag_pattern, name=package_basename) or _strip_v(current_ref)
-        )
-        latest_ver = (
-            parse_tag_version(latest_tag, tag_pattern, name=package_basename) or _strip_v(latest_tag)
+        current_ver = parse_tag_version(
+            current_ref, tag_pattern, name=package_basename
+        ) or _strip_v(current_ref)
+        latest_ver = parse_tag_version(latest_tag, tag_pattern, name=package_basename) or _strip_v(
+            latest_tag
         )
 
         if is_newer_version(current_ver, latest_ver):

src/apm_cli/marketplace/tag_pattern.py

@@ -32,6 +32,7 @@
     "v{version}",
     "{version}",
     "{name}_v{version}",
+    "{name}--v{version}",
     "{name}-v{version}",
 )
 
@@ -120,10 +121,7 @@ def build_tag_regex(pattern: str, *, name: str | None = None) -> re.Pattern[str]
     )
 
     escaped = escaped.replace(re.escape(_sentinel_version), _VERSION_RX)
-    if _PLACEHOLDER_NAME in pattern and name:
-        name_rx = re.escape(name)
-    else:
-        name_rx = r"[^/]+"
+    name_rx = re.escape(name) if _PLACEHOLDER_NAME in pattern and name else r"[^/]+"
     escaped = escaped.replace(re.escape(_sentinel_name), name_rx)
 
     return re.compile(r"^" + escaped + r"$")

tests/integration/marketplace/test_outdated_integration.py

@@ -61,6 +61,15 @@ def _refs_alpha():
     ]
 
 
+def _refs_alpha_named():
+    """alpha: monorepo-style tags with package name prefix."""
+    return [
+        RemoteRef(name="refs/tags/alpha_v1.0.0", sha="a" * 40),
+        RemoteRef(name="refs/tags/alpha_v1.1.0", sha="b" * 40),
+        RemoteRef(name="refs/tags/beta_v9.9.9", sha="c" * 40),
+    ]
+
+
 def _refs_beta():
     """beta: v2.0.0 only -- no newer version available."""
     return [
@@ -78,6 +87,7 @@ def _refs_pinned():
 def _side_effect(owner_repo: str):
     return {
         "org/alpha": _refs_alpha(),
+        "org/alpha-monorepo": _refs_alpha_named(),
         "org/beta": _refs_beta(),
         "org/pinned": _refs_pinned(),
     }.get(owner_repo, [])
@@ -206,6 +216,26 @@ def test_major_outside_range_is_noted(self, tmp_path: Path):
         # v2.0.0 is the latest overall; it should appear in the overall-latest column
         assert "v2.0.0" in combined
 
+    def test_name_underscore_tags_are_inferred_end_to_end(self, tmp_path: Path):
+        """Monorepo tags like alpha_v1.1.0 are reported through the CLI path."""
+        yml_content = """\
+name: outdated-test
+description: Marketplace for outdated tests
+version: 1.0.0
+owner:
+  name: Test Org
+packages:
+  - name: alpha
+    source: org/alpha-monorepo
+    version: "^1.0.0"
+    tags:
+      - test
+"""
+        result = _run_outdated(tmp_path, yml_content=yml_content)
+        assert result.exit_code == 1
+        assert "alpha_v1.1.0" in result.output
+        assert "beta_v9.9.9" not in result.output
+
 
 class TestOutdatedMissingYml:
     """outdated without marketplace.yml exits 1."""

tests/unit/marketplace/test_tag_pattern.py

@@ -222,6 +222,7 @@ class TestRoundTrip:
             ("{name}-v{version}", "my-tool", "2.0.0"),
             ("release-{version}", "x", "10.20.30"),
             ("{name}_v{version}", "tool", "1.0.0-beta.1"),
+            ("{name}--v{version}", "tool", "1.0.1"),
         ],
     )
     def test_roundtrip(self, pattern: str, name: str, version: str) -> None:
@@ -237,6 +238,9 @@ class TestInferTagPattern:
     def test_name_underscore_v_version(self) -> None:
         assert infer_tag_pattern("api-governance_v1.0.1") == "{name}_v{version}"
 
+    def test_name_double_dash_v_version(self) -> None:
+        assert infer_tag_pattern("api-governance--v1.0.1") == "{name}--v{version}"
+
     def test_name_underscore_v_scoped_to_package(self) -> None:
         assert infer_tag_pattern("apm1_v1.0.1", "apm1") == "{name}_v{version}"
         assert infer_tag_pattern("apm2_v1.0.1", "apm1") is None
@@ -258,6 +262,9 @@ class TestIsVersionTagRef:
     def test_name_underscore_v_version_is_tag(self) -> None:
         assert is_version_tag_ref("api-governance_v1.0.1") is True
 
+    def test_name_double_dash_v_version_is_tag(self) -> None:
+        assert is_version_tag_ref("api-governance--v1.0.1") is True
+
     def test_name_at_version_not_tag(self) -> None:
         assert is_version_tag_ref("api-governance@1.0.1") is False