`a8b3bca`

Clarify declared HTML link recovery

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

SHA: a8b3bca17a53734d51790aa3d7cef85b74bafdad
Parents: eabd30b
Tree: d31745d

4 changed files

Status	File	+	-
M	`src/loader/runtime/safeguard_services.py`	37	0
M	`src/loader/runtime/tool_batches.py`	12	1
M	`tests/test_safeguard_services.py`	5	0
M	`tests/test_tool_batches.py`	5	3

src/loader/runtime/safeguard_services.pymodified

  from __future__ import annotations
 +import os
  import re
  import shlex
  from dataclasses import dataclass
+             )
          if declared_preview:
              suggestion += f". Already-declared local targets include: {declared_preview}"
 +        allowed_hrefs = self._declared_html_hrefs_for_file(
 +            root,
 +            normalized,
 +            declared_targets,
 +        )
 +        if allowed_hrefs:
 +            allowed_preview = ", ".join(allowed_hrefs[:6])
 +            if len(allowed_hrefs) > 6:
 +                allowed_preview += ", ..."
 +            suggestion += f". Allowed hrefs from this file include: {allowed_preview}"
          declared_suggestions = self._suggest_declared_html_targets(
              declared_targets,
              undeclared_targets,
                  suggestions.append(candidate)
          return suggestions
++
 +    def _declared_html_hrefs_for_file(
 +        self,
 +        root: Path,
 +        file_path: Path,
 +        declared_targets: set[str],
 +    ) -> list[str]:
 +        try:
 +            source_directory = file_path.parent.resolve(strict=False)
 +            root_index = (root / "index.html").resolve(strict=False)
 +        except OSError:
 +            source_directory = file_path.parent.expanduser()
 +            root_index = (root / "index.html").expanduser()
++
 +        hrefs: list[str] = []
 +        if file_path.name.lower() != "index.html":
 +            hrefs.append(os.path.relpath(root_index, source_directory).replace(os.sep, "/"))
++
 +        for target in sorted(declared_targets):
 +            target_path = (root / target).resolve(strict=False)
 +            href = os.path.relpath(target_path, source_directory).replace(os.sep, "/")
 +            if href == "." or href in hrefs:
 +                continue
 +            hrefs.append(href)
 +        return hrefs
++
      def _validate_path(self, file_path: str) -> ValidationResult:
          if '\x00' in file_path:
              return ValidationResult(

src/loader/runtime/tool_batches.pymodified

              event_content,
              "Already-declared local targets include:",
+         )
 +        allowed_hrefs = _extract_blocked_html_target_list(
 +            event_content,
 +            "Allowed hrefs from this file include:",
 +        )
          guidance = (
              "That HTML mutation introduced sibling targets outside the current declared local-link set. "
              f"Stay on `{target}`."
+         )
 -        if closest_targets:
 +        if allowed_hrefs:
 +            guidance += (
 +                " Remove the invented hrefs and use only these exact href values "
 +                "from this file, or omit navigation links entirely: "
 +                + ", ".join(f"`{candidate}`" for candidate in allowed_hrefs[:6])
 +                + "."
 +            )
 +        elif closest_targets:
              guidance += (
                  " Remove the invented hrefs or replace them with the closest declared target(s): "
                  + ", ".join(f"`{candidate}`" for candidate in closest_targets[:3])

tests/test_safeguard_services.pymodified

          == "HTML page introduces new local targets outside the current declared artifact set"
+     )
      assert "advanced.html" in result.suggestion
 +    assert "Allowed hrefs from this file include:" in result.suggestion
 +    assert "../index.html" in result.suggestion
 +    assert "installation.html" in result.suggestion
  def test_pre_action_validator_blocks_chapter_write_with_existing_but_undeclared_sibling(
+     )
      assert "04-locations-and-servers.html" in result.suggestion
      assert "04-advanced-configuration.html" in result.suggestion
 +    assert "Allowed hrefs from this file include:" in result.suggestion
 +    assert "../index.html" in result.suggestion
  def test_pre_action_validator_does_not_suggest_unrelated_declared_html_target(

tests/test_tool_batches.pymodified

              "introducing new sibling targets that the guide root does not declare; remove or replace "
              "undeclared hrefs like: troubleshooting.html. "
              "Already-declared local targets include: chapters/introduction.html, chapters/installation.html, "
 -            "chapters/configuration.html."
 +            "chapters/configuration.html. Allowed hrefs from this file include: ../index.html, "
 +            "installation.html, configuration.html."
          ),
+     )
      assert queued
 -    assert "Remove the invented hrefs or keep local links within the declared target set" in queued[0]
 -    assert "`chapters/installation.html`" in queued[0]
 +    assert "use only these exact href values" in queued[0]
 +    assert "`installation.html`" in queued[0]
 +    assert "`../index.html`" in queued[0]
      assert "closest declared target(s)" not in queued[0]