Merge pull request #322 from ai-agent-assembly/v0.1.0/AAASM-4757/fix/sonar_smells

[AAASM-4757] ♻️ (examples): Clear 5 Sonar smells in generate_example_metadata

Author: Chisanan232

scripts/generate_example_metadata.py

@@ -242,12 +242,14 @@ def _sub(match: re.Match[str]) -> str:
 # or, inside a require ( ... ) block:
 #   \tgithub.com/ai-agent-assembly/go-sdk v0.0.1-rc.3
 # The regex captures the prefix (indent + optional "require ") so we preserve
-# whichever form the surrounding file uses. The tail requires whitespace before a
-# ``// comment`` so the version token ``\S+`` has an unambiguous, non-whitespace
-# boundary — otherwise the engine could backtrack ``\S+`` into the ``//``,
-# non-linear behavior static analysis flags as a ReDoS risk.
+# whichever form the surrounding file uses. The tail is a prefix-free alternation
+# — either whitespace before a ``// comment`` (``\s+//[^\n]*``) or bare trailing
+# whitespace (``\s*``). Written as ``(?:\s+//.*)?\s*`` instead, the comment's
+# ``.*`` and the trailing ``\s*`` both compete for trailing whitespace, a
+# super-linear ambiguity static analysis flags as a ReDoS risk (S8786); the
+# disjoint alternation removes that overlap while matching the same set.
 _GO_PIN_RE = re.compile(
-    r'''^(?P<prefix>\s*(?:require\s+)?)github\.com/ai-agent-assembly/go-sdk\s+\S+(?P<tail>(?:\s+//.*)?\s*)$''',
+    r'''^(?P<prefix>\s*(?:require\s+)?)github\.com/ai-agent-assembly/go-sdk\s+\S+(?P<tail>\s+//[^\n]*|\s*)$''',
     re.MULTILINE,
 )
 
@@ -451,8 +453,13 @@ def rewrite_go_readme(path: Path, sdk: GoSdk) -> bool:
 # alpha/beta/rc pre-release suffix. Only the version token is rewritten, so an
 # operator prefix (``>= ``) and any trailing note (``(with the LlamaIndex
 # adapter)``) are preserved verbatim.
+# The pre-release alternation is prefix-free: ``b(?:eta)?`` / ``a(?:lpha)?``
+# fold the ``beta``/``b`` and ``alpha``/``a`` pairs together so no branch is a
+# prefix of another. The flat ``(?:rc|beta|alpha|b|a)`` form has ``b``/``a``
+# shadowing ``beta``/``alpha``, the kind of alternation overlap static analysis
+# flags as super-linear (S8786); this folds it out while matching the same set.
 _VERSION_TOKEN_RE = re.compile(
-    r"v?\d+\.\d+\.\d+(?:[-.]?(?:rc|beta|alpha|b|a)\.?\d+)?"
+    r"v?\d+\.\d+\.\d+(?:[-.]?(?:rc|b(?:eta)?|a(?:lpha)?)\.?\d+)?"
 )
 
 
@@ -862,6 +869,25 @@ def _prereq_readmes(repo_root: Path) -> list[Path]:
     return out
 
 
+def _align_prereq_readme(
+    readme: Path,
+    labels: tuple[tuple[str, str], ...],
+    backtick_packages: tuple[tuple[str, str], ...],
+) -> bool:
+    """Align every prereq row/bullet in one README; return True if any changed."""
+
+    touched = False
+    for label, version in labels:
+        if rewrite_prereq_row(readme, label, version):
+            touched = True
+        if rewrite_prereq_bullet(readme, label, version):
+            touched = True
+    for package, version in backtick_packages:
+        if rewrite_prereq_backtick_row(readme, package, version):
+            touched = True
+    return touched
+
+
 def process_prereq_rows(repo_root: Path, versions: SdkVersions) -> list[Path]:
     """Align every hand-written ``Agent Assembly <Lang> SDK`` prereq row.
 
@@ -884,16 +910,7 @@ def process_prereq_rows(repo_root: Path, versions: SdkVersions) -> list[Path]:
     )
     changed: list[Path] = []
     for readme in _prereq_readmes(repo_root):
-        touched = False
-        for label, version in labels:
-            if rewrite_prereq_row(readme, label, version):
-                touched = True
-            if rewrite_prereq_bullet(readme, label, version):
-                touched = True
-        for package, version in backtick_packages:
-            if rewrite_prereq_backtick_row(readme, package, version):
-                touched = True
-        if touched:
+        if _align_prereq_readme(readme, labels, backtick_packages):
             changed.append(readme)
     return changed
 
@@ -1017,7 +1034,7 @@ def _audit_pins(repo_root: Path, versions: SdkVersions) -> list[str]:
 # pins are a bare ``"<version>"`` string and go pins are a bare ``go.mod``
 # version. The workflow rewriter already forces ``==`` on a bump, but this pass
 # also fails CI on a hand-authored bad operator before a regen runs.
-def _audit_py_operator(repo_root: Path, versions: SdkVersions) -> list[str]:
+def _audit_py_operator(repo_root: Path) -> list[str]:
     """Report every operator-bearing core-SDK pin that is not exact (``==``).
 
     Covers both the python manifests and the CI-workflow pip-install pins.
@@ -1038,6 +1055,102 @@ def _audit_py_operator(repo_root: Path, versions: SdkVersions) -> list[str]:
     return problems
 
 
+def _audit_prose_label(line: str, expected_by_label: dict[str, str]) -> str | None:
+    """Return a drift message for an ``Agent Assembly <Lang> SDK`` prose line."""
+
+    label_match = _PROSE_LABEL_RE.search(line)
+    if label_match is None:
+        return None
+    token_match = _VERSION_TOKEN_RE.search(line)
+    if token_match is None:
+        return None
+    expected = expected_by_label[label_match.group(1)]
+    if token_match.group(0) == expected:
+        return None
+    return f"states {token_match.group(0)!r}, expected {expected!r}"
+
+
+def _audit_prose_backtick(
+    line: str, backtick_checks: tuple[tuple[re.Pattern[str], str], ...]
+) -> list[str]:
+    """Return drift messages for backtick-``package``-labelled prereq rows."""
+
+    problems: list[str] = []
+    for row_re, expected in backtick_checks:
+        row_match = row_re.search(line)
+        if row_match is None:
+            continue
+        token_match = _VERSION_TOKEN_RE.search(row_match.group("val"))
+        if token_match is not None and token_match.group(0) != expected:
+            problems.append(f"states {token_match.group(0)!r}, expected {expected!r}")
+    return problems
+
+
+def _audit_prose_install(
+    line: str, install_checks: tuple[tuple[re.Pattern[str], str], ...]
+) -> list[str]:
+    """Return drift messages for raw install-hint literals on a prose line."""
+
+    problems: list[str] = []
+    for hint_re, expected in install_checks:
+        hint_match = hint_re.search(line)
+        if hint_match and hint_match.group("ver") != expected:
+            problems.append(
+                f"install hint pins {hint_match.group('ver')!r}, "
+                f"expected {expected!r}"
+            )
+    return problems
+
+
+def _audit_prose_line(
+    line: str,
+    in_block: bool,
+    expected_by_label: dict[str, str],
+    backtick_checks: tuple[tuple[re.Pattern[str], str], ...],
+    install_checks: tuple[tuple[re.Pattern[str], str], ...],
+) -> list[str]:
+    """Return every drift message for one prose line, in stable emit order.
+
+    Install hints are skipped inside the generated sdk-install block — that
+    block is generator-owned and the prose install-hint pass excludes it.
+    """
+
+    problems: list[str] = []
+    label_problem = _audit_prose_label(line, expected_by_label)
+    if label_problem is not None:
+        problems.append(label_problem)
+    problems.extend(_audit_prose_backtick(line, backtick_checks))
+    if not in_block:
+        problems.extend(_audit_prose_install(line, install_checks))
+    return problems
+
+
+def _audit_prose_file(
+    path: Path,
+    rel: Path,
+    expected_by_label: dict[str, str],
+    backtick_checks: tuple[tuple[re.Pattern[str], str], ...],
+    install_checks: tuple[tuple[re.Pattern[str], str], ...],
+) -> list[str]:
+    """Report drift for one README/doc, tracking the generated-block region."""
+
+    problems: list[str] = []
+    in_block = False
+    for lineno, line in _audit_lines(path):
+        if SDK_BLOCK_BEGIN in line:
+            in_block = True
+        elif SDK_BLOCK_END in line:
+            in_block = False
+            continue
+        if EXEMPT_MARKER in line:
+            continue
+        for suffix in _audit_prose_line(
+            line, in_block, expected_by_label, backtick_checks, install_checks
+        ):
+            problems.append(f"{rel}:{lineno}: {suffix}")
+    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.
 
@@ -1072,47 +1185,11 @@ def _audit_prose(repo_root: Path, versions: SdkVersions) -> list[str]:
     problems: list[str] = []
     for path in _globbed(repo_root, _README_GLOBS + ("docs/*.md",)):
         rel = path.relative_to(repo_root)
-        in_block = False
-        for lineno, line in _audit_lines(path):
-            if SDK_BLOCK_BEGIN in line:
-                in_block = True
-            elif SDK_BLOCK_END in line:
-                in_block = False
-                continue
-            if EXEMPT_MARKER in line:
-                continue
-
-            label_match = _PROSE_LABEL_RE.search(line)
-            if label_match:
-                token_match = _VERSION_TOKEN_RE.search(line)
-                if token_match is not None:
-                    expected = expected_by_label[label_match.group(1)]
-                    if token_match.group(0) != expected:
-                        problems.append(
-                            f"{rel}:{lineno}: states {token_match.group(0)!r}, "
-                            f"expected {expected!r}"
-                        )
-
-            for row_re, expected in backtick_checks:
-                row_match = row_re.search(line)
-                if row_match is None:
-                    continue
-                token_match = _VERSION_TOKEN_RE.search(row_match.group("val"))
-                if token_match is not None and token_match.group(0) != expected:
-                    problems.append(
-                        f"{rel}:{lineno}: states {token_match.group(0)!r}, "
-                        f"expected {expected!r}"
-                    )
-
-            if in_block:
-                continue
-            for hint_re, expected in install_checks:
-                hint_match = hint_re.search(line)
-                if hint_match and hint_match.group("ver") != expected:
-                    problems.append(
-                        f"{rel}:{lineno}: install hint pins "
-                        f"{hint_match.group('ver')!r}, expected {expected!r}"
-                    )
+        problems.extend(
+            _audit_prose_file(
+                path, rel, expected_by_label, backtick_checks, install_checks
+            )
+        )
     return problems
 
 
@@ -1121,7 +1198,7 @@ def audit(repo_root: Path, versions: SdkVersions) -> list[str]:
 
     return sorted(
         _audit_pins(repo_root, versions)
-        + _audit_py_operator(repo_root, versions)
+        + _audit_py_operator(repo_root)
         + _audit_prose(repo_root, versions)
     )