`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: