Add validation to explicitly check for bare AWS strings in excerpt descriptions.

There is technically more nuance, but this has caused more problems being loose than restrictive.

Author: DavidSouther

aws_doc_sdk_examples_tools/doc_gen_cli_test.py

@@ -5,8 +5,8 @@
 
 from .doc_gen import DocGen, MetadataError, Example
 from .doc_gen_cli import main
-from .metadata import DocFilenames, Sdk, Language, SDKPageVersion, Version
-from .sdks import SdkVersion
+from .metadata import DocFilenames, Language, SDKPageVersion, Version
+from .sdks import Sdk, SdkVersion
 
 
 @pytest.fixture
@@ -24,7 +24,7 @@ def mock_example():
             },
             sdk_pages={
                 "cpp": {
-                    1: SDKPageVersion(actions_scenarios={"medical-imaging": f"link"})
+                    1: SDKPageVersion(actions_scenarios={"medical-imaging": "link"})
                 }
             },
         ),

aws_doc_sdk_examples_tools/metadata.py

@@ -6,7 +6,7 @@
 
 from collections import defaultdict
 from dataclasses import dataclass, field
-from typing import Any, Dict, Literal, List, Optional, Set, Union, Iterable
+from typing import Dict, Literal, List, Optional, Set, Iterable
 from os.path import splitext
 from pathlib import Path
 
@@ -18,9 +18,7 @@
     ExampleMergeMismatchedLanguage,
     ExampleMergeConflict,
 )
-from .project_validator import ValidationConfig
-from .services import Service
-from .sdks import Sdk
+from .project_validator import verify_no_invalid_bare_aws
 
 
 @dataclass
@@ -44,8 +42,9 @@ class Excerpt:
     # all: This content was entirely written by GenAI, and has not been reviewed by a human.
     genai: Literal["none", "some", "most", "all"] = "none"
 
-    def validate(self, errors: MetadataErrors):
-        pass
+    def validate(self, errors: MetadataErrors, path: str):
+        if self.description:
+            verify_no_invalid_bare_aws(self.description, path, errors)
 
 
 @dataclass
@@ -63,7 +62,7 @@ class Version:
     # Link to additional topic places.
     more_info: List[Url] = field(default_factory=list)
 
-    def validate(self, errors: MetadataErrors, root: Path):
+    def validate(self, errors: MetadataErrors, root: Path, path: str):
         github = self.github
         if github is not None:
             _, ext = splitext(github)
@@ -82,8 +81,8 @@ def validate(self, errors: MetadataErrors, root: Path):
                     )
                 )
 
-        for excerpt in self.excerpts:
-            excerpt.validate(errors)
+        for i, excerpt in enumerate(self.excerpts):
+            excerpt.validate(errors, f"{path}[{i}]")
 
 
 @dataclass
@@ -117,10 +116,10 @@ def merge(self, other: "Language", errors: MetadataErrors):
             # within the language. If a tributary or writer feels they need to
             # modify an excerpt, they should go modify the excerpt directly.
 
-    def validate(self, errors: MetadataErrors, root: Path):
+    def validate(self, errors: MetadataErrors, root: Path, path: str):
         errs = MetadataErrors()
-        for version in self.versions:
-            version.validate(errs, root)
+        for i, version in enumerate(self.versions):
+            version.validate(errs, root, f"{path}[{i}]")
         for error in errs:
             if isinstance(error, MetadataParseError):
                 error.language = self.name
@@ -189,8 +188,8 @@ def merge(self, other: Example, errors: MetadataErrors):
 
     def validate(self, errors: MetadataErrors, root: Path):
         errs = MetadataErrors()
-        for language in self.languages.values():
-            language.validate(errs, root)
+        for name, language in self.languages.items():
+            language.validate(errs, root, f"{self.file}: {self.id}.languages.{name}")
         for error in errs:
             error.file = self.file
             error.id = self.id

aws_doc_sdk_examples_tools/metadata_test.py

@@ -22,7 +22,7 @@
     Excerpt,
 )
 from .doc_gen import DocGen, parse_examples, check_id_format
-from .project_validator import ValidationConfig
+from .project_validator import ValidationConfig, InvalidBareAWS
 from .sdks import Sdk
 from .services import Service, ServiceExpanded
 
@@ -977,5 +977,39 @@ def test_no_duplicate_title_abbrev():
     assert expected == [*errors]
 
 
+def test_excerpt_with_bare_aws():
+    errors = MetadataErrors()
+    doc_gen = DocGen(
+        Path(__file__).parent / "test_excerpt_with_bare_aws",
+        errors=errors,
+        examples={
+            "a": Example(
+                id="a",
+                file=Path("a"),
+                title_abbrev="abbr",
+                category="cat",
+                languages={
+                    "java": Language(
+                        name="java", property="java", versions=[Version(sdk_version=1, excerpts=[Excerpt(description="Bare AWS Here", snippet_files=[], snippet_tags=[])])]
+                    )
+                },
+                services={"svc": set()},
+            ),
+        },
+    )
+    doc_gen.validate()
+
+    expected = [
+        InvalidBareAWS(
+            file=Path("a"),
+            id="a",
+            content="Bare AWS Here",
+            path="a: a.languages.java[0][0]"
+        )
+    ]
+
+    assert expected == [*errors]
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-vv"])

aws_doc_sdk_examples_tools/project_validator.py

@@ -24,7 +24,7 @@
 import logging
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Set
+from typing import Dict, List, Set
 
 from .file_utils import get_files
 from .metadata_errors import (
@@ -206,3 +206,20 @@ def verify_no_secret_keys(
     keys -= validation.allow_list
     for word in keys:
         errors.append(PossibleSecretKey(file=file_location, word=word))
+
+
+@dataclass
+class InvalidBareAWS(MetadataError):
+    content: str = ""
+    path: str = ""
+
+    def message(self):
+        return f"Possible bare AWS in {self.path} ({self.content})"
+
+
+BARE_AWS_REGEX = r"\bAWS\s+[A-Za-z0-9]+\b"
+
+
+def verify_no_invalid_bare_aws(content: str, path: str, errors: MetadataErrors):
+    if re.findall(BARE_AWS_REGEX, content):
+        errors.append(InvalidBareAWS(content=content, path=path))