graphddb-runtime 0.5.1__tar.gz → 0.5.2__tar.gz

{graphddb_runtime-0.5.1 → graphddb_runtime-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.5.1
+Version: 0.5.2
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.5.1 → graphddb_runtime-0.5.2}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.5.1
+Version: 0.5.2
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.5.1 → graphddb_runtime-0.5.2}/graphddb_runtime.egg-info/SOURCES.txt

@@ -23,6 +23,8 @@ graphddb_runtime.egg-info/top_level.txt
 tests/test_concurrency.py
 tests/test_contract_runtime.py
 tests/test_description.py
+tests/test_description_followups.py
+tests/test_description_jsdoc.py
 tests/test_integration.py
 tests/test_integration_command.py
 tests/test_integration_compose.py

{graphddb_runtime-0.5.1 → graphddb_runtime-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.5.1"
+version = "0.5.2"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"

graphddb_runtime-0.5.2/tests/test_description_followups.py

@@ -0,0 +1,65 @@
+"""Issue #166 (follow-up of #154): the description taken in on the relation and GSI
+TS declaration sites is propagated into the generated artifacts the Python bridge
+consumes — manifest.json (entity relations / gsis) and the generated Python source
+(relation field comment, GSI query-method docstring). An undescribed relation / GSI
+carries no `description` key (backward compatible). TS↔Python parity holds because
+both read the SAME serialized string from the manifest.
+
+The `@maintainedFrom` maintenance IR is deliberately kept OFF manifest.json /
+operations.json / the generated Python (a maintenance-graph concern, not a manifest
+one), so there is nothing to assert Python-side for that site; its description is a
+metadata-layer capture verified in the TS suite
+(__tests__/spec/description-relation-maintained-gsi.test.ts).
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+
+import conftest
+
+REPOSITORIES_PATH = os.path.join(conftest.FIXTURES_DIR, "repositories.py")
+TYPES_PATH = os.path.join(conftest.FIXTURES_DIR, "types.py")
+# The multi fixture is the one whose queries actually SELECT relations, so it is where
+# a relation's field comment surfaces in the generated types.py.
+_MULTI_DIR = os.path.join(os.path.dirname(conftest.FIXTURES_DIR), "generated_multi")
+MULTI_TYPES_PATH = os.path.join(_MULTI_DIR, "types.py")
+
+
+def _manifest() -> dict:
+    with open(conftest.MANIFEST_PATH, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def test_manifest_carries_relation_description() -> None:
+    group = _manifest()["entities"]["GroupModel"]
+    assert (
+        group["relations"]["members"]["description"]
+        == "Memberships linking users into this group."
+    )
+    # A relation without a declared description carries no `description` key.
+    assert "description" not in group["relations"]["permissions"]
+
+
+def test_manifest_carries_gsi_description() -> None:
+    user = _manifest()["entities"]["UserModel"]
+    gsi1 = next(g for g in user["gsis"] if g["indexName"] == "GSI1")
+    assert gsi1["description"] == "Look up a user by their unique email address."
+
+
+def test_generated_python_carries_gsi_method_docstring() -> None:
+    with open(REPOSITORIES_PATH, encoding="utf-8") as fh:
+        repos_src = fh.read()
+    ast.parse(repos_src)
+    # The GSI description surfaces as the docstring of the query that reads GSI1.
+    assert '"""Look up a user by their unique email address."""' in repos_src
+
+
+def test_generated_python_carries_relation_field_comment() -> None:
+    with open(MULTI_TYPES_PATH, encoding="utf-8") as fh:
+        types_src = fh.read()
+    ast.parse(types_src)
+    # The `members` relation's description surfaces as a trailing field comment.
+    assert "# Memberships linking users into this group." in types_src

graphddb_runtime-0.5.2/tests/test_description_jsdoc.py

@@ -0,0 +1,99 @@
+"""Issue #165: JSDoc doc-comments extracted via a TS compiler-API pass become the
+DEFAULT `description` (an explicit `description` still wins). These JSDoc-sourced
+strings must reach the SAME generated artifacts the Python bridge consumes —
+manifest.json / operations.json and the generated Python source — proving TS↔Python
+parity (both read the one serialized string from the generated SSoT).
+
+The committed fixtures (python/tests/fixtures/{models,definitions}.ts) carry JSDoc at
+sites left WITHOUT an explicit description by #154/#166 (UserModel entity + its
+`name` field + `groups` relation, GroupMembershipModel's `GSI1`, and the `getUser`
+query + its `userId` param), plus one PRECEDENCE control (GroupModel has both a JSDoc
+and an explicit description — the explicit must win, the JSDoc must be absent).
+Regenerate with `npm run gen:py:fixtures[:multi]`.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+
+import conftest
+
+REPOSITORIES_PATH = os.path.join(conftest.FIXTURES_DIR, "repositories.py")
+TYPES_PATH = os.path.join(conftest.FIXTURES_DIR, "types.py")
+OPERATIONS_PATH = os.path.join(conftest.FIXTURES_DIR, "operations.json")
+
+
+def _manifest() -> dict:
+    with open(conftest.MANIFEST_PATH, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _operations() -> dict:
+    with open(OPERATIONS_PATH, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def test_manifest_carries_jsdoc_model_description() -> None:
+    user = _manifest()["entities"]["UserModel"]
+    assert "JSDoc-as-default (model)" in user["description"]
+
+
+def test_manifest_carries_jsdoc_field_description() -> None:
+    user = _manifest()["entities"]["UserModel"]
+    assert user["fields"]["name"]["description"] == (
+        "#165 JSDoc-as-default (field): the user's display name."
+    )
+
+
+def test_manifest_carries_jsdoc_relation_description() -> None:
+    user = _manifest()["entities"]["UserModel"]
+    assert user["relations"]["groups"]["description"] == (
+        "#165 JSDoc-as-default (relation): the groups this user is a member of."
+    )
+
+
+def test_manifest_carries_jsdoc_gsi_description() -> None:
+    membership = _manifest()["entities"]["GroupMembershipModel"]
+    gsi1 = next(g for g in membership["gsis"] if g["indexName"] == "GSI1")
+    assert gsi1["description"] == (
+        "#165 JSDoc-as-default (gsi): list a user's group memberships (reverse index)."
+    )
+
+
+def test_operations_carry_jsdoc_query_and_param_description() -> None:
+    get_user = _operations()["queries"]["getUserDocumented"]
+    assert get_user["description"] == (
+        "#165 JSDoc-as-default (query): fetch a single user by id (JSDoc source)."
+    )
+    assert get_user["params"]["userId"]["description"] == (
+        "#165 JSDoc-as-default (param): the user id to fetch."
+    )
+
+
+def test_generated_python_carries_jsdoc_query_docstring() -> None:
+    with open(REPOSITORIES_PATH, encoding="utf-8") as fh:
+        repos_src = fh.read()
+    ast.parse(repos_src)
+    assert (
+        '"""#165 JSDoc-as-default (query): fetch a single user by id (JSDoc source)."""'
+        in repos_src
+    )
+
+
+def test_generated_python_carries_jsdoc_field_comment() -> None:
+    with open(TYPES_PATH, encoding="utf-8") as fh:
+        types_src = fh.read()
+    ast.parse(types_src)
+    assert "# #165 JSDoc-as-default (field): the user's display name." in types_src
+
+
+def test_explicit_description_overrides_jsdoc() -> None:
+    """GroupModel carries BOTH a JSDoc and an explicit `@model({ description })` —
+    the explicit string must win and the JSDoc must be absent everywhere."""
+    manifest = _manifest()
+    group = manifest["entities"]["GroupModel"]
+    assert group["description"] == "A group that users belong to."
+    # The precedence-control JSDoc must not have leaked into the manifest.
+    assert "PRECEDENCE CONTROL" not in json.dumps(manifest)