Merge pull request #314 from ai-agent-assembly/v0.0.1/AAASM-4721/enforce_exact_pin

[AAASM-4721] ✨ (examples): Enforce exact-pin operator on the core SDK

Author: Chisanan232

scripts/generate_example_metadata.py

@@ -193,10 +193,14 @@ def rewrite_python_manifest(path: Path, sdk: PythonSdk) -> bool:
     text = path.read_text(encoding="utf-8")
 
     def _sub(match: re.Match[str]) -> str:
+        # Normalize the operator to exact ``==``. The core SDK pin must never be a
+        # floor/open range (AAASM-4704 and the repo's "never a bare >=" rule),
+        # so a bump self-heals a drifted operator; the --check audit enforces the
+        # same invariant. The regex still captures ``op`` so a non-``==`` pin is
+        # matched and rewritten.
         indent = match.group("indent")
-        op = match.group("op")
         tail = match.group("tail")
-        return f'{indent}"{sdk.package}{op}{sdk.version}"{tail}'
+        return f'{indent}"{sdk.package}=={sdk.version}"{tail}'
 
     new_text = _PY_PIN_RE.sub(_sub, text)
     return _write_if_changed(path, new_text)
@@ -755,7 +759,7 @@ def process_prereq_rows(repo_root: Path, versions: SdkVersions) -> list[Path]:
 # exactly ``@agent-assembly/sdk``; the go id is exactly
 # ``github.com/ai-agent-assembly/go-sdk`` followed by whitespace.
 _PY_PIN_AUDIT_RE = re.compile(
-    r"(?<![\w/@.-])agent-assembly(?:==|>=|~=|<=|!=|<|>)(?P<ver>[^\"'\s,]+)"
+    r"(?<![\w/@.-])agent-assembly(?P<op>==|>=|~=|<=|!=|<|>)(?P<ver>[^\"'\s,]+)"
 )
 _NODE_PIN_AUDIT_RE = re.compile(r'"@agent-assembly/sdk"\s*:\s*"(?P<ver>[^"]+)"')
 _GO_PIN_AUDIT_RE = re.compile(
@@ -816,6 +820,30 @@ def _audit_pins(repo_root: Path, versions: SdkVersions) -> list[str]:
     return problems
 
 
+# The core SDK pin must be exact (``==``): a floor (``>=``) or open range lets a
+# resolver pull a future major and silently break an example (AAASM-4704, and the
+# repo's own "never a bare >=" rule). The version-drift audit above only checks
+# the version token, so this pass enforces the operator separately. Python
+# manifests are the only core-SDK pins that carry an operator — node pins are a
+# bare ``"<version>"`` string and go pins are a bare ``go.mod`` version.
+def _audit_py_operator(repo_root: Path, versions: SdkVersions) -> list[str]:
+    """Report every python core-SDK pin whose operator is not exact (``==``)."""
+
+    problems: list[str] = []
+    for path in _globbed(repo_root, _PY_PIN_GLOBS):
+        for lineno, line in _audit_lines(path):
+            if EXEMPT_MARKER in line:
+                continue
+            match = _PY_PIN_AUDIT_RE.search(line)
+            if match and match.group("op") != "==":
+                rel = path.relative_to(repo_root)
+                problems.append(
+                    f"{rel}:{lineno}: uses {match.group('op')!r} operator on the "
+                    f"core SDK pin, expected '=='"
+                )
+    return problems
+
+
 def _audit_prose(repo_root: Path, versions: SdkVersions) -> list[str]:
     """Report every README/doc prose line whose SDK version drifts from the SoT.
 
@@ -854,7 +882,9 @@ def audit(repo_root: Path, versions: SdkVersions) -> list[str]:
     """Return every drifted SDK-version literal as a sorted ``file:line`` list."""
 
     return sorted(
-        _audit_pins(repo_root, versions) + _audit_prose(repo_root, versions)
+        _audit_pins(repo_root, versions)
+        + _audit_py_operator(repo_root, versions)
+        + _audit_prose(repo_root, versions)
     )
 
 

scripts/test_generate_example_metadata.py

@@ -219,5 +219,46 @@ def test_ignores_runtime_subpackage_and_org_path(self) -> None:
         self.assertEqual(gen.audit(self.root, self.versions), [])
 
 
+class PythonPinOperatorTests(_RepoTestCase):
+    def test_audit_flags_non_exact_operator(self) -> None:
+        # Correct version, floor operator: the version-drift audit is clean, but
+        # the operator policy is violated (AAASM-4704).
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "python/ex/pyproject.toml",
+            'dependencies = [\n    "agent-assembly>=0.0.1rc5",\n]\n',
+        )
+        problems = gen.audit(self.root, self.versions)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("python/ex/pyproject.toml:2", problems[0])
+        self.assertIn("operator", problems[0])
+
+    def test_audit_passes_on_exact_operator(self) -> None:
+        _in_sync_tree(self.root)  # every python pin is ``==``
+        self.assertEqual(gen.audit(self.root, self.versions), [])
+
+    def test_operator_exemption_is_honored(self) -> None:
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "python/ex/pyproject.toml",
+            'dependencies = [\n    "agent-assembly>=0.0.1rc5",'
+            "  # sdk-version-exempt\n]\n",
+        )
+        self.assertEqual(gen.audit(self.root, self.versions), [])
+
+    def test_rewriter_normalizes_operator_to_exact(self) -> None:
+        path = _write(
+            self.root,
+            "python/ex/pyproject.toml",
+            'dependencies = [\n    "agent-assembly>=0.0.1rc3",\n]\n',
+        )
+        changed = gen.rewrite_python_manifest(path, self.versions.python)
+        self.assertTrue(changed)
+        self.assertIn('"agent-assembly==0.0.1rc5"', path.read_text())
+        self.assertNotIn(">=", path.read_text())
+
+
 if __name__ == "__main__":
     unittest.main()