nthlayer-common 2.1.0__tar.gz → 2.1.2__tar.gz

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nthlayer-common
-Version: 2.1.0
+Version: 2.1.2
 Summary: Shared utilities for the NthLayer ecosystem
 License: Apache-2.0
 Requires-Python: >=3.11

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nthlayer-common"
-version = "2.1.0"
+version = "2.1.2"
 description = "Shared utilities for the NthLayer ecosystem"
 readme = "README.md"
 requires-python = ">=3.11"

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/src/nthlayer_common/manifest/__init__.py

@@ -98,12 +98,12 @@ __all__ = [
     "VALID_TIERS",
     # Service-type helpers
     "is_valid_service_type",
-    # Directory scanning (opensrm-3470)
+    "resolve_service_type",
+    "valid_service_types_phrase",
+    # Directory scanning
     "MANIFEST_SUFFIXES",
     "foreign_yaml_reason",
     "iter_manifest_files",
-    "resolve_service_type",
-    "valid_service_types_phrase",
     # Enums
     "DependencyCriticality",
     "SourceFormat",

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/src/nthlayer_common/manifest/scan.py

@@ -26,6 +26,7 @@ from pathlib import Path
 
 import yaml
 
+from nthlayer_common.manifest.models import is_valid_service_type
 from nthlayer_common.manifest.parser.v1 import is_srm_v1_format
 from nthlayer_common.manifest.parser.v2 import is_opensrm_v2_format
 
@@ -38,8 +39,10 @@ MANIFEST_SUFFIXES = (".yaml", ".yml")
 def iter_manifest_files(specs_dir: str | Path) -> list[Path]:
     """Every ``.yaml``/``.yml`` file directly under ``specs_dir``, sorted.
 
-    Sorted because callers dedupe on a first-wins basis: unsorted, which
-    manifest wins for a service with two files would vary by filesystem.
+    Sorted so the order is stable across machines. That matters to any
+    caller that dedupes first-wins — learn/retrospective does; observe's
+    spec_loader does not, and whether it should is opensrm-3470's follow-up
+    rather than a property this function can assume.
 
     Returns empty for a path that is not a directory rather than raising,
     so a caller that wants its own error message for that case keeps the
@@ -48,7 +51,21 @@ def iter_manifest_files(specs_dir: str | Path) -> list[Path]:
     path = Path(specs_dir)
     if not path.is_dir():
         return []
-    return sorted(p for p in path.iterdir() if p.suffix in MANIFEST_SUFFIXES)
+    # `not p.is_dir()` rather than `p.is_file()`: excluding DIRECTORIES was
+    # the point — a directory named `foo.yaml` would be counted as a broken
+    # manifest by every caller. is_file() also excludes a dangling symlink,
+    # which silently drops a stale overlay link that previously reached
+    # load_manifest and was counted.
+    #
+    # Suffix compared case-folded: `.YAML` was excluded outright — never
+    # loaded, never counted, never logged — which is the silent-subset-by-
+    # extension failure MANIFEST_SUFFIXES exists to prevent, one case-fold
+    # away.
+    return sorted(
+        p
+        for p in path.iterdir()
+        if not p.is_dir() and p.suffix.lower() in MANIFEST_SUFFIXES
+    )
 
 
 def foreign_yaml_reason(spec_file: str | Path) -> str | None:
@@ -77,9 +94,10 @@ def foreign_yaml_reason(spec_file: str | Path) -> str | None:
     its body is indistinguishable in principle from any other headerless
     YAML mapping — both are dicts with no apiVersion, no kind, no
     ``spec.service``. No content heuristic separates those, and adding more
-    markers would not change it. Such a file is dropped; the caller should
-    record it at debug so an investigator chasing a number that looks wrong
-    can pick the trail back up.
+    markers would not change it. For such a file this returns a reason, so
+    the caller can record it rather than drop it without trace — which is
+    what lets an investigator chasing a number that looks wrong pick the
+    trail back up.
     """
     path = Path(spec_file)
     try:
@@ -117,11 +135,42 @@ def foreign_yaml_reason(spec_file: str | Path) -> str | None:
     if near_miss:
         return None
 
+    # Body recovery: a bad merge or a mis-indent can strip the header while
+    # leaving the body intact, and that is the common corruption.
+    #
+    # The key names differ by format, and getting them wrong makes this whole
+    # branch inert — which it was until opensrm-3470's edge-cases pass:
+    #   v1  spec.slos          a MAPPING of name -> config (parser/v1 does
+    #                          slos_data.items()), not a list
+    #   v2  spec.slo           a list of OpenSLO documents
+    #       spec.judgment_slo  a list
+    #       spec.service       a MAPPING; OpenSLO writes the same key as a
+    #                          plain string, which is what keeps OpenSLO out
+    #       spec.outcomes      a mapping
+    #   v1  spec.type          REQUIRED by parse_srm_v1 (v1.py:91), and
+    #                          checked against is_valid_service_type rather
+    #                          than "is a string": a Backstage catalog-info
+    #                          carries spec.type too (`service`, `library`),
+    #                          and counting those makes every Backstage
+    #                          Component in the directory a broken manifest
+    #   v2  spec.owner         REQUIRED by parse_opensrm_v2 (v2.py:104)
+    # spec.slos is accepted as either shape: v1 writes a mapping, and a
+    # partially-converted file is exactly the kind of thing that lands here.
+    #
+    # The required keys matter most: a file carrying the one key its format
+    # cannot be parsed without makes a stronger claim to being a manifest
+    # than any of the optional ones above. Checking only the optional keys
+    # was the same mistake as testing spec.slos for the wrong type —
+    # reasoning about shapes without asking what the parsers demand.
     spec = data.get("spec")
     if isinstance(spec, dict) and (
         isinstance(spec.get("service"), dict)
-        or isinstance(spec.get("slos"), list)
+        or isinstance(spec.get("slos"), (dict, list))
+        or isinstance(spec.get("slo"), list)
+        or isinstance(spec.get("judgment_slo"), list)
         or isinstance(spec.get("outcomes"), dict)
+        or is_valid_service_type(spec.get("type"))
+        or isinstance(spec.get("owner"), dict)
     ):
         return None
 

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/src/nthlayer_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nthlayer-common
-Version: 2.1.0
+Version: 2.1.2
 Summary: Shared utilities for the NthLayer ecosystem
 License: Apache-2.0
 Requires-Python: >=3.11

{nthlayer_common-2.1.0 → nthlayer_common-2.1.2}/tests/test_manifest_scan.py

@@ -16,9 +16,8 @@ have now happened in nthlayer-workers:
 
 ``foreign_yaml_reason`` is that question, promoted here from
 ``nthlayer_workers.learn.retrospective`` so the three call sites that need
-it stop reaching into each other (opensrm-3470). ``iter_manifest_files``
-comes with it because ``.yml`` blindness is the same silent-subset bug
-reached by file extension rather than parse error.
+it stop reaching into each other (opensrm-3470). ``iter_manifest_files`` comes with it — see MANIFEST_SUFFIXES for why both
+suffixes, always.
 
 These tests are ported from the workers suite deliberately: the promotion
 must be behaviour-preserving, and porting the contract is how that is
@@ -54,7 +53,10 @@ _AIMING = {
     # Header stripped by a bad merge or a mis-indent, body intact. This is the
     # common corruption, and the case the gate's last extension exists for.
     "headerless, spec.service mapping": "spec:\n  service:\n    name: s\n    type: api\n",
-    "headerless, spec.slos": "spec:\n  slos:\n    - name: availability\n",
+    # v1 writes spec.slos as a MAPPING of name -> config. Encoding it as a
+    # list here is what let the inert-guard bug hide: the fixture agreed
+    # with the broken predicate instead of with the parser.
+    "headerless, spec.slos mapping": "spec:\n  slos:\n    availability:\n      target: 99.9\n",
     "headerless, spec.outcomes": "spec:\n  outcomes:\n    decision_value: {}\n",
     # A typo'd kind or a drifted API group is an ordinary way a real manifest
     # breaks: aiming at us and missing still counts.
@@ -158,3 +160,142 @@ def test_iter_manifest_files_on_a_missing_directory_is_empty(tmp_path):
     """Callers check is_dir() for their own error messages; this returning
     empty rather than raising keeps that their decision."""
     assert iter_manifest_files(tmp_path / "nope") == []
+
+
+def test_iter_manifest_files_skips_directories(tmp_path):
+    """A DIRECTORY named ``foo.yaml`` is not a manifest file — every caller
+    would otherwise count it as a manifest that failed to load."""
+    (tmp_path / "subdir.yaml").mkdir()
+    (tmp_path / "real.yaml").write_text("spec: {}\n")
+
+    assert [p.name for p in iter_manifest_files(tmp_path)] == ["real.yaml"]
+
+
+# =============================================================================
+# The body-recovery step must fire for REAL manifest shapes
+# =============================================================================
+#
+# opensrm-oh27's fifth and final gate iteration added body recovery: a bad
+# merge or a mis-indent can strip the header while leaving the body intact,
+# and that is the common corruption. It was landed as "the last extension"
+# on the grounds that the remaining leak was unclosable in principle.
+#
+# It was inert. `spec.slos` was tested with isinstance(..., list), but v1
+# writes it as a MAPPING (parser/v1.py does slos_data.items()), and v2 does
+# not use `spec.slos` at all — its keys are `spec.slo` and
+# `spec.judgment_slo`. So the branch never fired for any real manifest, in
+# either format, and a header-stripped manifest was dropped as foreign with
+# parse_failures == 0: the exact silent subset this bead family exists to
+# remove, inside the guard meant to prevent it.
+#
+# Found by opensrm-3470's edge-cases pass. Not caught earlier because the
+# promotion was verified against the ORIGINAL, which had the same defect —
+# faithful copying proves faithfulness, not correctness.
+
+
+@pytest.mark.parametrize(
+    ("label", "body"),
+    [
+        # v1: spec.slos is a mapping of name -> config
+        ("v1 slos mapping", "spec:\n  type: api\n  slos:\n    availability:\n      target: 99.9\n"),
+        # v2: a list of OpenSLO documents
+        ("v2 slo list", "spec:\n  slo:\n    - apiVersion: openslo/v1\n      kind: SLO\n"),
+        # v2: judgment SLOs
+        ("v2 judgment_slo", "spec:\n  judgment_slo:\n    - metadata: {name: j}\n"),
+        # already covered, kept so a regression in either direction shows here
+        ("v2 service mapping", "spec:\n  service:\n    name: s\n    type: api\n"),
+        ("v2 outcomes", "spec:\n  outcomes:\n    decision_value: {}\n"),
+    ],
+)
+def test_headerless_manifest_bodies_are_recovered(tmp_path, label, body):
+    """A header-stripped manifest must COUNT, not be dropped as foreign."""
+    path = tmp_path / "x.yaml"
+    path.write_text(body)
+
+    assert foreign_yaml_reason(path) is None, (
+        f"{label}: a headerless manifest body was classified as foreign YAML, "
+        f"so it would be dropped with parse_failures == 0"
+    )
+
+
+def test_openslo_still_excluded_after_widening_the_body_check(tmp_path):
+    """Widening body recovery must not start swallowing OpenSLO documents.
+
+    OpenSLO writes spec.service as a STRING and has spec.objectives; it has
+    no spec.slos/slo/judgment_slo. If widening broke this, every OpenSLO file
+    in a specs directory would start counting as a broken manifest.
+    """
+    path = tmp_path / "x.yaml"
+    path.write_text("spec:\n  service: my-svc\n  objectives:\n    - target: 0.99\n")
+
+    assert foreign_yaml_reason(path) is not None
+
+
+@pytest.mark.parametrize("name", ["a.YAML", "b.Yml", "c.YmL"])
+def test_iter_manifest_files_is_case_insensitive_on_suffix(tmp_path, name):
+    """`.YAML` was excluded — never loaded, never counted, never logged.
+
+    The same silent-subset-by-extension failure MANIFEST_SUFFIXES exists to
+    prevent, one case-fold away."""
+    (tmp_path / name).write_text("spec: {}\n")
+
+    assert [p.name for p in iter_manifest_files(tmp_path)] == [name]
+
+
+def test_a_dangling_symlink_is_still_listed(tmp_path):
+    """is_file() follows symlinks, so a broken one vanished from the listing.
+
+    Before the is_file() guard it reached load_manifest and raised, so it was
+    counted. Silently dropping a stale overlay symlink is a regression the
+    guard introduced; excluding directories was the point, not excluding
+    everything that is not a readable file.
+    """
+    (tmp_path / "broken.yaml").symlink_to(tmp_path / "does-not-exist.yaml")
+
+    assert [p.name for p in iter_manifest_files(tmp_path)] == ["broken.yaml"]
+
+
+@pytest.mark.parametrize(
+    ("label", "body"),
+    [
+        # parser/v1.py:91 — "spec.type is required"
+        ("v1 required type", "spec:\n  type: api\n  dependencies:\n    - name: x\n"),
+        # parser/v2.py:104 — "spec.owner is required in v2 manifests"
+        ("v2 required owner", "spec:\n  owner:\n    group: group:default/t\n  contracts: []\n"),
+    ],
+)
+def test_body_recovery_covers_the_keys_the_parsers_require(tmp_path, label, body):
+    """Body recovery checked OPTIONAL keys and omitted the required ones.
+
+    A file carrying the one key its format cannot be parsed without is about
+    as strong a claim to being a manifest as a body can make — stronger than
+    the optional keys already accepted. Same class as the inert-list bug: a
+    predicate reasoning about shapes without checking what the parsers
+    actually demand.
+    """
+    path = tmp_path / "x.yaml"
+    path.write_text(body)
+
+    assert foreign_yaml_reason(path) is None, f"{label} was dropped as foreign"
+
+
+def test_backstage_component_is_not_a_manifest(tmp_path):
+    """A Backstage catalog-info.yaml carries `spec.type` and `spec.owner` too.
+
+    Accepting any string `spec.type` as a manifest marker counts every
+    Backstage Component in a specs directory as a broken manifest — the
+    noisy direction, which is how a coverage caveat stops being read.
+
+    `spec.type` only counts when it is a value OpenSRM would accept:
+    `service` is not one, `api` is. Backstage's `spec.owner` is a string
+    where v2's is a mapping, so that marker already discriminates.
+    """
+    path = tmp_path / "catalog-info.yaml"
+    path.write_text(
+        "apiVersion: backstage.io/v1alpha1\n"
+        "kind: Component\n"
+        "metadata: {name: svc}\n"
+        "spec: {type: service, lifecycle: production, owner: team-a}\n"
+    )
+
+    assert foreign_yaml_reason(path) is not None