fix: address Copilot review round 11 findings

- Fix _parse_semver() return type annotation and docstring to reflect
  that it returns packaging.version.Version or tuple[int, ...]
- Fail closed on DNS resolution errors in check_url_reachable() to
  prevent SSRF bypass via unresolvable-then-resolvable hostnames
- Remove dead documentation field code from _build_preset_entry() since
  the preset issue template has no documentation URL field
- Update catalog-generate-table.py docstring to match --target behavior
  (exits with error when markers missing, not print to stdout)
- Document that extension table Category/Effect columns require catalog
  schema extension to be populated
- Update presets/DEVELOPING.md tag comment from 2-5 to 2-10

Author: mnriem

.github/scripts/catalog-generate-table.py

@@ -2,7 +2,8 @@
 """Generate a markdown table from a community catalog JSON file.
 
 Reads a catalog.community.json and replaces content between marker comments
-in a target markdown file.  If the markers are not present the table is
+in a target markdown file.  When ``--target`` is provided and markers are
+missing, the script exits with an error.  Without ``--target`` the table is
 printed to stdout.
 
 Markers expected in the markdown file:
@@ -100,7 +101,12 @@ def _provides_str_extension(provides: dict) -> str:
 
 
 def build_extension_table(catalog: dict) -> str:
-    """Build a markdown table for extensions."""
+    """Build a markdown table for extensions.
+
+    Note: Category and Effect columns will be empty unless the catalog
+    entries include ``category`` and ``effect`` fields (not yet part of
+    the standard catalog schema).
+    """
     entries = catalog.get("extensions", {})
     lines: list[str] = []
     lines.append("| Extension | Purpose | Category | Effect | URL |")

.github/scripts/catalog-validate.py

@@ -155,8 +155,12 @@ def _present(value: str | None) -> bool:
     return bool(value and value.strip() and value.strip() != "_No response_")
 
 
-def _parse_semver(version: str) -> tuple[int, ...]:
-    """Parse a semver string into a comparable tuple of ints."""
+def _parse_semver(version: str):
+    """Parse a version string into a comparable object.
+
+    Returns a ``packaging.version.Version`` when the library is available,
+    otherwise a tuple of ints (major, minor, patch).
+    """
     try:
         from packaging.version import Version
         return Version(version)
@@ -300,7 +304,9 @@ def check_url_reachable(
                     f"{field_name} URL `{url}` resolves to a private/reserved address."
                 )
     except (socket.gaierror, ValueError):
-        pass  # DNS resolution may fail for unreachable hosts — let urlopen handle it
+        return False, (
+            f"{field_name} URL `{url}` could not be resolved."
+        )
 
     _gh_hosts = {"github.com", "www.github.com", "codeload.github.com", "raw.githubusercontent.com"}
     _is_github = hostname in _gh_hosts
@@ -766,9 +772,9 @@ def _build_preset_entry(
     elif is_update and "extensions" in existing.get("requires", {}):
         requires["extensions"] = existing["requires"]["extensions"]
 
-    # Documentation URL: use existing on update, fall back to repo/blob/main/README.md
-    documentation = _clean(fields.get("documentation", ""))
-    if not documentation and is_update:
+    # Documentation URL: preserve on update, fall back to repo/blob/main/README.md
+    documentation = ""
+    if is_update:
         documentation = existing.get("documentation", "")
     if not documentation:
         documentation = repo + "/blob/main/README.md"

presets/DEVELOPING.md

@@ -63,7 +63,7 @@ provides:
       description: "Custom spec template"
       replaces: "spec-template"
 
-tags:                              # 2-5 relevant tags
+tags:                              # 2-10 relevant tags
   - "category"
   - "workflow"
 ```