unitysvc-core 0.2.34__tar.gz → 0.2.35__tar.gz

{unitysvc_core-0.2.34/src/unitysvc_core.egg-info → unitysvc_core-0.2.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.34
+Version: 0.2.35
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -136,7 +136,11 @@ MIT
 ### Required enrollment parameter usage
 
 The shared validator rejects required user parameters that no channel, interface,
-or document consumes. File validation checks a listing against its paired offering
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
 when present; backend ingest calls the same `validate_required_parameter_usage`
 helper with the complete listing and offering. Schema declarations alone are not
 consumers. Jinja attribute access, string-key lookups, and `params.get("name")`

{unitysvc_core-0.2.34 → unitysvc_core-0.2.35}/README.md

@@ -101,7 +101,11 @@ MIT
 ### Required enrollment parameter usage
 
 The shared validator rejects required user parameters that no channel, interface,
-or document consumes. File validation checks a listing against its paired offering
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
 when present; backend ingest calls the same `validate_required_parameter_usage`
 helper with the complete listing and offering. Schema declarations alone are not
 consumers. Jinja attribute access, string-key lookups, and `params.get("name")`

{unitysvc_core-0.2.34 → unitysvc_core-0.2.35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.34"
+version = "0.2.35"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_core-0.2.34 → unitysvc_core-0.2.35}/src/unitysvc_core/parameter_usage.py

@@ -2,6 +2,12 @@
 
 This checks that required parameters have consumers. It does not prove that
 an intended enrollment channel consumes them; interface/document use counts.
+
+Only the fields the platform renders with an enrollment's ``params`` are
+consumers: the offering's channels (``upstream_access_config``), the listing's
+interfaces (``user_access_interfaces``) and document content. Metadata such as
+``display_name`` or ``description`` is never rendered with ``params``, so a
+reference there does not count (unitysvc/unitysvc#2649).
 """
 
 from typing import Any
@@ -66,6 +72,31 @@ def unused_required_params(parameters_schema: dict[str, Any] | None, *sources: A
     return [name for name in required if name not in used]
 
 
+# Keys of a document entry that hold its rendered content. Backend ingest sees
+# a ``.j2`` document's template source inlined as ``file_content``; the seller
+# validator inlines the same file before calling this module.
+_DOCUMENT_CONTENT_KEYS = ("file_content", "content")
+
+
+def _document_contents(documents: Any) -> list[str]:
+    entries = documents.values() if isinstance(documents, dict) else documents if isinstance(documents, list) else ()
+    out: list[str] = []
+    for doc in entries:
+        if isinstance(doc, dict):
+            out.extend(doc[key] for key in _DOCUMENT_CONTENT_KEYS if isinstance(doc.get(key), str))
+    return out
+
+
+def consumer_sources(listing: dict[str, Any], offering: dict[str, Any]) -> list[Any]:
+    """The parts of a service the platform renders with enrollment ``params``."""
+    return [
+        offering.get("upstream_access_config"),
+        listing.get("user_access_interfaces"),
+        _document_contents(listing.get("documents")),
+        _document_contents(offering.get("documents")),
+    ]
+
+
 def validate_required_parameter_usage(listing: dict[str, Any], offering: dict[str, Any]) -> list[str]:
     """Return hard validation errors, shared by seller validation and backend ingest.
 
@@ -75,15 +106,15 @@ def validate_required_parameter_usage(listing: dict[str, Any], offering: dict[st
     if listing.get("status") == "deprecated" or offering.get("status") == "deprecated":
         return []
     schema = listing.get("user_parameters_schema") or listing.get("parameters_schema")
-    content = {k: v for k, v in listing.items() if k not in ("user_parameters_schema", "parameters_schema")}
     try:
-        unused = unused_required_params(schema, content, offering)
+        unused = unused_required_params(schema, *consumer_sources(listing, offering))
     except TemplateSyntaxError as exc:
         return [f"Cannot validate required parameter usage: invalid Jinja template: {exc}"]
     if not unused:
         return []
     return [
-        f"Required user parameter(s) {', '.join(unused)} are used by no channel, interface or document. "
+        f"Required user parameter(s) {', '.join(unused)} are used by no channel (upstream_access_config), "
+        "interface (user_access_interfaces) or document content. "
         "Reference each one as {{ params.NAME }} (for example ${ customer_secrets.{{ params.NAME }} }), "
         "or drop it from the required list."
     ]

{unitysvc_core-0.2.34 → unitysvc_core-0.2.35}/src/unitysvc_core/validator.py

@@ -1027,9 +1027,33 @@ class DataValidator:
             except Exception as exc:
                 return [f"Cannot check required parameter usage: {exc}"]
             if isinstance(offering, dict) and (offering.get("schema") == "offering_v1" or candidate.stem == "offering"):
-                return validate_required_parameter_usage(listing, offering)
+                return validate_required_parameter_usage(
+                    self._with_template_documents(listing, file_path.parent),
+                    self._with_template_documents(offering, candidate.parent),
+                )
         return []
 
+    @staticmethod
+    def _with_template_documents(data: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+        """``data`` with each ``.j2`` document's template source inlined as
+        ``file_content``, as the seller SDK uploads it — so the seller check
+        sees the same document content backend ingest does."""
+        documents = data.get("documents")
+        if not isinstance(documents, dict):
+            return data
+        inlined: dict[str, Any] = {}
+        for title, doc in documents.items():
+            if isinstance(doc, dict) and "file_content" not in doc:
+                rel = doc.get("file_path")
+                if isinstance(rel, str) and rel.endswith(".j2"):
+                    path = Path(rel) if Path(rel).is_absolute() else base_dir / rel
+                    try:
+                        doc = {**doc, "file_content": path.read_text(encoding="utf-8")}
+                    except OSError:
+                        pass  # a missing file is reported by the file-reference checks
+            inlined[title] = doc
+        return {**data, "documents": inlined}
+
     def _resolve_provider_name(self, file_path: Path) -> str | None:
         """Find the provider name (``provider_v1.name``) governing a listing file.
 

{unitysvc_core-0.2.34 → unitysvc_core-0.2.35/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.34
+Version: 0.2.35
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -136,7 +136,11 @@ MIT
 ### Required enrollment parameter usage
 
 The shared validator rejects required user parameters that no channel, interface,
-or document consumes. File validation checks a listing against its paired offering
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
 when present; backend ingest calls the same `validate_required_parameter_usage`
 helper with the complete listing and offering. Schema declarations alone are not
 consumers. Jinja attribute access, string-key lookups, and `params.get("name")`

unitysvc_core-0.2.35/tests/test_parameter_usage.py

@@ -0,0 +1,185 @@
+"""Required enrollment parameters must have consumers across service data."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from unitysvc_core.parameter_usage import referenced_param_names, validate_required_parameter_usage
+from unitysvc_core.validator import DataValidator
+
+
+@pytest.mark.parametrize("expression", ["params.name", "params['name']", 'params.get("name")'])
+def test_named_reads(expression):
+    assert referenced_param_names("{{ " + expression + " }}") == {"name"}
+
+
+@pytest.mark.parametrize(
+    "expression",
+    [
+        "params",
+        "params | tojson",
+        "params.items()",
+        "params.keys()",
+        "params.values()",
+        "params.get(key)",
+        "params[key]",
+    ],
+)
+def test_dynamic_and_whole_map_reads(expression):
+    assert referenced_param_names("{{ " + expression + " }}") is None
+
+
+def test_strings_comments_and_non_template_text_are_not_consumers():
+    assert referenced_param_names(["params.name", "{# params.name #}", '{{ "params.name" }}']) == set()
+
+
+def listing(**changes):
+    return {"status": "ready", "user_parameters_schema": {"required": ["host", "token"]}, **changes}
+
+
+def channel(**fields):
+    """An offering whose one channel carries ``fields``."""
+    return {"upstream_access_config": {"plus": fields}}
+
+
+def test_required_names_in_the_schema_do_not_count_as_use():
+    errors = validate_required_parameter_usage(
+        listing(), {"upstream_access_config": {"free": {"api_key": "${ customer_secrets.TOKEN }"}}}
+    )
+    assert len(errors) == 1
+    assert "host, token are used by no channel" in errors[0]
+
+
+@pytest.mark.parametrize(
+    ("listing_changes", "offering"),
+    [
+        ({"display_name": "{{ params.host }} {{ params.token }}"}, {}),
+        ({"description": "{{ params.host }}", "summary": "{{ params.token }}"}, {}),
+        ({}, {"description": "{{ params.host }} {{ params.token }}", "name": "{{ params.host }}"}),
+        # a document's metadata is not its content
+        ({"documents": {"Doc": {"description": "{{ params.host }} {{ params.token }}"}}}, {}),
+        ({"service_options": {"note": "{{ params.host }} {{ params.token }}"}}, {}),
+    ],
+)
+def test_metadata_is_not_a_consumer(listing_changes, offering):
+    """Only channels, interfaces and document content are rendered with
+    params; a reference anywhere else must not satisfy the rule (#2649)."""
+    errors = validate_required_parameter_usage(listing(**listing_changes), offering)
+    assert len(errors) == 1
+    assert "host, token are used by no channel" in errors[0]
+
+
+def test_dynamic_use_in_metadata_does_not_disable_the_rule():
+    errors = validate_required_parameter_usage(listing(description="{{ params | tojson }}"), {})
+    assert "host, token" in errors[0]
+
+
+def test_partial_use_is_rejected():
+    errors = validate_required_parameter_usage(listing(), channel(base_url="{{ params.host }}"))
+    assert "token are used by no channel" in errors[0]
+
+
+def test_channel_interface_and_document_reads_count_without_proving_attribution():
+    data = listing(documents={"example": {"file_content": "{{ params.token }}"}})
+    assert validate_required_parameter_usage(data, channel(base_url="{{ params.host }}")) == []
+    assert (
+        validate_required_parameter_usage(
+            listing(
+                user_access_interfaces={"canonical": {"base_url": "{{ params.host }}"}},
+                documents={"Example": {"file_content": "{{ params.token }}"}},
+            ),
+            {},
+        )
+        == []
+    )
+    # offering-level document content counts too
+    assert (
+        validate_required_parameter_usage(
+            listing(),
+            {**channel(base_url="{{ params.host }}"), "documents": {"Doc": {"file_content": "{{ params.token }}"}}},
+        )
+        == []
+    )
+
+
+def test_required_parameter_can_have_punctuation_in_its_name():
+    assert (
+        validate_required_parameter_usage(
+            listing(user_parameters_schema={"required": ["host-name"]}), channel(host="{{ params['host-name'] }}")
+        )
+        == []
+    )
+
+
+def test_deprecated_content_can_be_retired():
+    assert validate_required_parameter_usage(listing(status="deprecated"), {}) == []
+    assert validate_required_parameter_usage(listing(), {"status": "deprecated"}) == []
+
+
+def test_no_required_parameters():
+    assert validate_required_parameter_usage({}, {}) == []
+
+
+@pytest.mark.parametrize("suffix", ["json", "toml"])
+def test_file_validator_checks_paired_offering(tmp_path, suffix):
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    data = listing()
+    (tmp_path / "listing.json").write_text(json.dumps(data))
+    path = tmp_path / f"offering.{suffix}"
+    path.write_text("{}" if suffix == "json" else "")
+    errors = validator.validate_required_parameter_usage(data, tmp_path / "listing.json")
+    assert "host, token" in errors[0]
+    path.write_text(
+        json.dumps(channel(host="{{ params.host }}", token="{{ params.token }}"))
+        if suffix == "json"
+        else '[upstream_access_config.plus]\nhost = "{{ params.host }}"\ntoken = "{{ params.token }}"\n'
+    )
+    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
+
+
+def test_file_validator_reads_template_documents_like_ingest(tmp_path):
+    """The seller SDK uploads a .j2 document's source as file_content, so the
+    file validator must count a param used only there, as ingest does."""
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    (tmp_path / "offering.json").write_text(json.dumps(channel(base_url="{{ params.host }}")))
+    (tmp_path / "connectivity.sh.j2").write_text('curl "$URL" -H "X-Token: {{ params.token }}"\n')
+    data = listing(documents={"Connectivity": {"file_path": "connectivity.sh.j2", "category": "connectivity_test"}})
+    (tmp_path / "listing.json").write_text(json.dumps(data))
+    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
+    # a non-template document is uploaded as-is, never rendered: not a consumer
+    (tmp_path / "usage.md").write_text("{{ params.token }}")
+    data = listing(documents={"Usage": {"file_path": "usage.md"}})
+    errors = validator.validate_required_parameter_usage(data, tmp_path / "listing.json")
+    assert "token are used by no channel" in errors[0]
+
+
+def test_validation_pipeline_invokes_the_shared_rule(tmp_path, monkeypatch):
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    path = tmp_path / "listing.json"
+    path.write_text(json.dumps({"name": "labs/test"}))
+    calls = []
+
+    def check(data, file_path):
+        calls.append(file_path)
+        return ["unused-param-sentinel"]
+
+    monkeypatch.setattr(validator, "validate_required_parameter_usage", check)
+    valid, errors = validator.validate_data_file(path, "listing_v1")
+    assert not valid
+    assert "unused-param-sentinel" in errors
+    assert calls == [path]
+
+
+def test_invalid_jinja_does_not_bypass_the_rule():
+    errors = validate_required_parameter_usage(listing(), channel(base_url="{{ params.host"))
+    assert "invalid Jinja template" in errors[0]
+
+
+def test_invalid_jinja_in_metadata_is_ignored():
+    """Metadata is never rendered with params, so it is not parsed either."""
+    errors = validate_required_parameter_usage(listing(description="Go: {{ .Name }}"), {})
+    assert "host, token are used by no channel" in errors[0]

unitysvc_core-0.2.34/tests/test_parameter_usage.py

@@ -1,121 +0,0 @@
-"""Required enrollment parameters must have consumers across service data."""
-
-import json
-from pathlib import Path
-
-import pytest
-
-from unitysvc_core.parameter_usage import referenced_param_names, validate_required_parameter_usage
-from unitysvc_core.validator import DataValidator
-
-
-@pytest.mark.parametrize("expression", ["params.name", "params['name']", 'params.get("name")'])
-def test_named_reads(expression):
-    assert referenced_param_names("{{ " + expression + " }}") == {"name"}
-
-
-@pytest.mark.parametrize(
-    "expression",
-    [
-        "params",
-        "params | tojson",
-        "params.items()",
-        "params.keys()",
-        "params.values()",
-        "params.get(key)",
-        "params[key]",
-    ],
-)
-def test_dynamic_and_whole_map_reads(expression):
-    assert referenced_param_names("{{ " + expression + " }}") is None
-
-
-def test_strings_comments_and_non_template_text_are_not_consumers():
-    assert referenced_param_names(["params.name", "{# params.name #}", '{{ "params.name" }}']) == set()
-
-
-def listing(**changes):
-    return {"status": "ready", "user_parameters_schema": {"required": ["host", "token"]}, **changes}
-
-
-def test_required_names_in_the_schema_do_not_count_as_use():
-    errors = validate_required_parameter_usage(
-        listing(), {"upstream_access_config": {"free": {"api_key": "${ customer_secrets.TOKEN }"}}}
-    )
-    assert len(errors) == 1
-    assert "host, token are used by no channel" in errors[0]
-
-
-def test_partial_use_is_rejected():
-    errors = validate_required_parameter_usage(listing(), {"host": "{{ params.host }}"})
-    assert "token are used by no channel" in errors[0]
-
-
-def test_channel_interface_and_document_reads_count_without_proving_attribution():
-    data = listing(documents={"example": {"body": "{{ params.token }}"}})
-    assert validate_required_parameter_usage(data, {"host": "{{ params.host }}"}) == []
-    assert (
-        validate_required_parameter_usage(
-            listing(user_access_interfaces={"url": "{{ params.host }}"}, documents={"body": "{{ params.token }}"}), {}
-        )
-        == []
-    )
-
-
-def test_required_parameter_can_have_punctuation_in_its_name():
-    assert (
-        validate_required_parameter_usage(
-            listing(user_parameters_schema={"required": ["host-name"]}), {"host": "{{ params['host-name'] }}"}
-        )
-        == []
-    )
-
-
-def test_deprecated_content_can_be_retired():
-    assert validate_required_parameter_usage(listing(status="deprecated"), {}) == []
-    assert validate_required_parameter_usage(listing(), {"status": "deprecated"}) == []
-
-
-def test_no_required_parameters():
-    assert validate_required_parameter_usage({}, {}) == []
-
-
-@pytest.mark.parametrize("suffix", ["json", "toml"])
-def test_file_validator_checks_paired_offering(tmp_path, suffix):
-    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
-    validator = DataValidator(tmp_path, schema_dir)
-    data = listing()
-    (tmp_path / "listing.json").write_text(json.dumps(data))
-    path = tmp_path / f"offering.{suffix}"
-    path.write_text("{}" if suffix == "json" else "")
-    errors = validator.validate_required_parameter_usage(data, tmp_path / "listing.json")
-    assert "host, token" in errors[0]
-    path.write_text(
-        json.dumps({"host": "{{ params.host }}", "token": "{{ params.token }}"})
-        if suffix == "json"
-        else 'host = "{{ params.host }}"\ntoken = "{{ params.token }}"\n'
-    )
-    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
-
-
-def test_validation_pipeline_invokes_the_shared_rule(tmp_path, monkeypatch):
-    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
-    validator = DataValidator(tmp_path, schema_dir)
-    path = tmp_path / "listing.json"
-    path.write_text(json.dumps({"name": "labs/test"}))
-    calls = []
-
-    def check(data, file_path):
-        calls.append(file_path)
-        return ["unused-param-sentinel"]
-
-    monkeypatch.setattr(validator, "validate_required_parameter_usage", check)
-    valid, errors = validator.validate_data_file(path, "listing_v1")
-    assert not valid
-    assert "unused-param-sentinel" in errors
-    assert calls == [path]
-
-
-def test_invalid_jinja_does_not_bypass_the_rule():
-    errors = validate_required_parameter_usage(listing(), {"host": "{{ params.host"})
-    assert "invalid Jinja template" in errors[0]