`bba591d`

Reject thin guide chapters

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 1 week ago

SHA: bba591d61151d031678ee6f8a23343decfd3362a
Parents: 4db4c36
Tree: 28ad414

2 changed files

Status	File	+	-
M	`src/loader/runtime/safeguard_services.py`	74	0
M	`tests/test_safeguard_services.py`	99	0

src/loader/runtime/safeguard_services.pymodified

  class PreActionValidator:
      """Validates tool calls before execution to catch problematic actions."""
 +    HTML_GUIDE_CHAPTER_MIN_TEXT_CHARS = 1200
 +    HTML_GUIDE_CHAPTER_MIN_BLOCKS = 12
 +    HTML_GUIDE_CHAPTER_MIN_DECLARED_LINKS = 4
++
      HTML_PLACEHOLDER_PATTERNS = [
+         (
              re.compile(r"\bstarter\s+(?:content|overview)\b", re.IGNORECASE),
          if not html_asset_result.valid:
              return html_asset_result
 +        html_guide_substance_result = self._validate_html_substantive_guide_content(
 +            str(file_path),
 +            str(content),
 +        )
 +        if not html_guide_substance_result.valid:
 +            return html_guide_substance_result
++
          html_root_coverage_result = self._validate_html_root_link_coverage(
              str(file_path),
              str(content),
              severity="error",
+         )
 +    def _validate_html_substantive_guide_content(
 +        self,
 +        file_path: str,
 +        content: str,
 +    ) -> ValidationResult:
 +        normalized = Path(file_path).expanduser()
 +        if normalized.suffix.lower() not in {".html", ".htm"}:
 +            return ValidationResult(valid=True)
 +        if normalized.name.lower() in {"index.html", "index.htm"}:
 +            return ValidationResult(valid=True)
 +        if not _html_text_looks_like_document(content):
 +            return ValidationResult(valid=True)
++
 +        root = self._resolve_html_artifact_root(normalized)
 +        current_relative = self._relative_html_target(root, normalized)
 +        if current_relative is None:
 +            return ValidationResult(valid=True)
 +        relative_parts = Path(current_relative).parts
 +        if not relative_parts or relative_parts[0] not in {"chapters", "chapter"}:
 +            return ValidationResult(valid=True)
++
 +        declared_targets, authoritative_root_graph = self._collect_declared_html_targets(
 +            root,
 +            normalized,
 +        )
 +        if (
 +            not authoritative_root_graph
 +            or current_relative not in declared_targets
 +            or len(declared_targets) < self.HTML_GUIDE_CHAPTER_MIN_DECLARED_LINKS
 +        ):
 +            return ValidationResult(valid=True)
++
 +        text_without_tags = re.sub(r"<[^>]+>", " ", content)
 +        plain_text = re.sub(r"\s+", " ", text_without_tags).strip()
 +        content_blocks = len(
 +            re.findall(
 +                r"<(p|li|pre|code|section|article|table|h2|h3|h4)\b",
 +                content,
 +                re.IGNORECASE,
 +            )
 +        )
 +        if (
 +            len(plain_text) >= self.HTML_GUIDE_CHAPTER_MIN_TEXT_CHARS
 +            and content_blocks >= self.HTML_GUIDE_CHAPTER_MIN_BLOCKS
 +        ):
 +            return ValidationResult(valid=True)
++
 +        return ValidationResult(
 +            valid=False,
 +            reason="HTML guide chapter content is too thin",
 +            suggestion=(
 +                "This looks like a root-declared multi-page guide chapter. Write a "
 +                "substantive chapter before creating it: include concrete explanations, "
 +                "commands, examples, lists, and troubleshooting/detail sections. "
 +                f"Current content has {len(plain_text)} text chars and "
 +                f"{content_blocks} structured block(s); expected at least "
 +                f"{self.HTML_GUIDE_CHAPTER_MIN_TEXT_CHARS} text chars and "
 +                f"{self.HTML_GUIDE_CHAPTER_MIN_BLOCKS} structured blocks. For an "
 +                "equally thorough guide, aim comfortably above that floor."
 +            ),
 +            severity="error",
 +        )
++
      def _validate_numbered_sibling_conflict(self, file_path: str) -> ValidationResult:
          path = Path(file_path).expanduser()
          if path.exists() or not path.suffix or not path.parent.exists():

tests/test_safeguard_services.pymodified

      assert result.valid is True
 +def test_pre_action_validator_blocks_thin_root_declared_guide_chapter(
 +    tmp_path: Path,
 +) -> None:
 +    validator = PreActionValidator()
 +    guide = tmp_path / "guides" / "nginx"
 +    chapters = guide / "chapters"
 +    chapters.mkdir(parents=True)
 +    (guide / "index.html").write_text(
 +        "<html><body>"
 +        '<a href="chapters/01-introduction.html">Introduction</a>'
 +        '<a href="chapters/02-installation.html">Installation</a>'
 +        '<a href="chapters/03-configuration.html">Configuration</a>'
 +        '<a href="chapters/04-reverse-proxy.html">Reverse Proxy</a>'
 +        "</body></html>"
 +    )
++
 +    result = validator.validate(
 +        "write",
 +        {
 +            "file_path": str(chapters / "01-introduction.html"),
 +            "content": (
 +                '<!DOCTYPE html><html lang="en"><body><h1>Introduction</h1>'
 +                "<p>Nginx is a web server and reverse proxy.</p>"
 +                '<p><a href="../index.html">Back</a></p></body></html>'
 +            ),
 +        },
 +    )
++
 +    assert result.valid is False
 +    assert result.reason == "HTML guide chapter content is too thin"
 +    assert "root-declared multi-page guide chapter" in result.suggestion
 +    assert "text chars" in result.suggestion
 +    assert "structured block" in result.suggestion
++
++
 +def test_pre_action_validator_allows_small_non_guide_html_chapter(
 +    tmp_path: Path,
 +) -> None:
 +    validator = PreActionValidator()
 +    page = tmp_path / "scratch" / "chapters" / "01-note.html"
 +    page.parent.mkdir(parents=True)
++
 +    result = validator.validate(
 +        "write",
 +        {
 +            "file_path": str(page),
 +            "content": (
 +                '<!DOCTYPE html><html lang="en"><body><h1>Note</h1>'
 +                "<p>Small standalone HTML is allowed outside a root-declared guide.</p>"
 +                "</body></html>"
 +            ),
 +        },
 +    )
++
 +    assert result.valid is True
++
++
 +def test_pre_action_validator_allows_substantive_root_declared_guide_chapter(
 +    tmp_path: Path,
 +) -> None:
 +    validator = PreActionValidator()
 +    guide = tmp_path / "guides" / "nginx"
 +    chapters = guide / "chapters"
 +    chapters.mkdir(parents=True)
 +    (guide / "index.html").write_text(
 +        "<html><body>"
 +        '<a href="chapters/01-introduction.html">Introduction</a>'
 +        '<a href="chapters/02-installation.html">Installation</a>'
 +        '<a href="chapters/03-configuration.html">Configuration</a>'
 +        '<a href="chapters/04-reverse-proxy.html">Reverse Proxy</a>'
 +        "</body></html>"
 +    )
 +    paragraph = (
 +        "Concrete Nginx guide content with commands, examples, tradeoffs, "
 +        "checks, and operational context. "
 +    )
 +    sections = "".join(
 +        (
 +            f"<h2>Section {index}</h2>"
 +            f"<p>{paragraph * 3}</p>"
 +            f"<ul><li>Action {index}</li><li>Verification {index}</li></ul>"
 +        )
 +        for index in range(1, 8)
 +    )
++
 +    result = validator.validate(
 +        "write",
 +        {
 +            "file_path": str(chapters / "01-introduction.html"),
 +            "content": (
 +                f'<!DOCTYPE html><html lang="en"><body><h1>Introduction</h1>{sections}'
 +                '<p><a href="../index.html">Back</a></p></body></html>'
 +            ),
 +        },
 +    )
++
 +    assert result.valid is True
++
++
  def test_pre_action_validator_blocks_new_root_index_parent_html_link(
      tmp_path: Path,
  ) -> None: