`35c0bcb`

Block TOC quality inflation

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

SHA: 35c0bcb767b7d5678001e6a51d97bb28675b0316
Parents: 7b1c338
Tree: 7165e37

4 changed files

Status	File	+
M	`src/loader/runtime/finalization.py`	4
M	`src/loader/runtime/safeguard_services.py`	93
M	`tests/test_finalization.py`	2
M	`tests/test_safeguard_services.py`	91

src/loader/runtime/finalization.pymodified

          "exceed the expected text-character floor; if it says insufficient "
          "structured content, add enough real sections, lists, code, tables, or "
          "other content blocks to exceed the block floor.",
 +        "- Treat structured content as substantive page body material, not table-of-"
 +        "contents inflation: do not add duplicate navigation entries, relabel links "
 +        "to existing pages as new chapters, or introduce new missing page links just "
 +        "to increase block counts.",
+     ]

src/loader/runtime/safeguard_services.pymodified

          if not html_link_scope_result.valid:
              return html_link_scope_result
 +        if Path(file_path).expanduser().exists():
 +            html_index_result = self._validate_html_index_links(
 +                str(file_path),
 +                str(content),
 +            )
 +            if not html_index_result.valid:
 +                return html_index_result
++
 +        html_duplicate_root_links_result = (
 +            self._validate_html_root_duplicate_local_links(
 +                str(file_path),
 +                str(content),
 +            )
 +        )
 +        if not html_duplicate_root_links_result.valid:
 +            return html_duplicate_root_links_result
++
          html_declared_target_result = self._validate_html_declared_target_set(
              str(file_path),
              str(content),
          if not html_index_result.valid:
              return html_index_result
 +        html_duplicate_root_links_result = (
 +            self._validate_html_root_duplicate_local_links(
 +                str(file_path),
 +                prospective_content,
 +            )
 +        )
 +        if not html_duplicate_root_links_result.valid:
 +            return html_duplicate_root_links_result
++
          html_declared_target_result = self._validate_html_declared_target_set(
              str(file_path),
              prospective_content,
          return ValidationResult(valid=True)
 +    def _validate_html_root_duplicate_local_links(
 +        self,
 +        file_path: str,
 +        content: str,
 +    ) -> ValidationResult:
 +        normalized = Path(file_path).expanduser()
 +        if normalized.suffix.lower() != ".html" or normalized.name.lower() != "index.html":
 +            return ValidationResult(valid=True)
++
 +        root = self._resolve_html_artifact_root(normalized)
 +        labels_by_target: dict[str, list[str]] = {}
 +        for _href, resolved, label in self._collect_local_html_link_labels(
 +            normalized,
 +            content,
 +        ):
 +            relative_target = self._relative_html_target(root, resolved)
 +            if relative_target is None:
 +                continue
 +            labels = labels_by_target.setdefault(relative_target, [])
 +            normalized_label = " ".join(label.split())
 +            if normalized_label and normalized_label not in labels:
 +                labels.append(normalized_label)
++
 +        conflicting: list[str] = []
 +        for target, labels in labels_by_target.items():
 +            if len(labels) < 3:
 +                continue
 +            conflicting.append(f"{target} ({', '.join(labels[:3])})")
++
 +        if not conflicting:
 +            return ValidationResult(valid=True)
++
 +        preview = "; ".join(conflicting[:2])
 +        if len(conflicting) > 2:
 +            preview += "; ..."
 +        return ValidationResult(
 +            valid=False,
 +            reason="HTML root page repeats one local page as multiple distinct links",
 +            suggestion=(
 +                "Do not inflate a root index or table of contents by pointing many "
 +                "different entries at the same local page. Expand substantive body "
 +                "content in the target files, create any new pages before linking them, "
 +                f"or keep one accurate entry per local page. Repeated target(s): {preview}"
 +            ),
 +            severity="error",
 +        )
++
      def _prospective_edit_content(
          self,
          file_path: str,
              targets.append((href, resolved))
          return targets
 +    def _collect_local_html_link_labels(
 +        self,
 +        file_path: Path,
 +        content: str,
 +    ) -> list[tuple[str, Path, str]]:
 +        pattern = re.compile(
 +            r"<a\b[^>]*href\s*=\s*[\"']([^\"']+)[\"'][^>]*>(.*?)</a>",
 +            re.IGNORECASE | re.DOTALL,
 +        )
 +        targets: list[tuple[str, Path, str]] = []
 +        for href, raw_label in pattern.findall(content):
 +            target_text = self._strip_local_href_target(href)
 +            if target_text is None or not self._is_local_html_link_target(target_text):
 +                continue
 +            resolved = (file_path.parent / target_text).resolve(strict=False)
 +            label = re.sub(r"<[^>]+>", " ", raw_label)
 +            label = re.sub(r"\s+", " ", label).strip()
 +            targets.append((href, resolved, label))
 +        return targets
++
      def _collect_local_href_targets(
          self,
          file_path: Path,

tests/test_finalization.pymodified

      assert f"Improve `{chapter_paths[0]}`: thin content" in guidance
      assert f"Improve `{chapter_paths[-1]}`: thin content" in guidance
      assert "add enough concrete prose" in guidance
 +    assert "not table-of-contents inflation" in guidance
 +    assert "do not add duplicate navigation entries" in guidance
      assert "do not stop after touching only the first file" in guidance
      assert repair is not None
      assert repair.artifact_path == str(chapter_paths[0].resolve(strict=False))

tests/test_safeguard_services.pymodified

      assert result.valid is True
 +def test_pre_action_validator_blocks_existing_root_write_with_far_missing_links(
 +    tmp_path: Path,
 +) -> None:
 +    validator = PreActionValidator()
 +    guide = tmp_path / "guides" / "nginx"
 +    chapters = guide / "chapters"
 +    chapters.mkdir(parents=True)
 +    for index, name in enumerate(
 +        [
 +            "introduction",
 +            "installation",
 +            "configuration",
 +            "virtual-hosts",
 +            "reverse-proxy",
 +            "load-balancing",
 +            "security",
 +        ],
 +        start=1,
 +    ):
 +        (chapters / f"{index:02d}-{name}.html").write_text("<html></html>\n")
 +    index = guide / "index.html"
 +    index.write_text(
 +        "\n".join(
 +            f'<li><a href="chapters/{path.name}">Chapter {number}</a></li>'
 +            for number, path in enumerate(sorted(chapters.glob("*.html")), start=1)
 +        )
 +    )
++
 +    result = validator.validate(
 +        "write",
 +        {
 +            "file_path": str(index),
 +            "content": (
 +                index.read_text()
 +                + "\n"
 +                '<li><a href="chapters/08-performance.html">Chapter 8</a></li>\n'
 +                '<li><a href="chapters/09-ssl.html">Chapter 9</a></li>\n'
 +                '<li><a href="chapters/10-monitoring.html">Chapter 10</a></li>\n'
 +            ),
 +        },
 +    )
++
 +    assert result.valid is False
 +    assert result.reason == "Edited HTML links point to files that do not exist"
 +    assert "chapters/09-ssl.html" in result.suggestion
++
++
 +def test_pre_action_validator_blocks_toc_inflation_with_duplicate_page_links(
 +    tmp_path: Path,
 +) -> None:
 +    validator = PreActionValidator()
 +    guide = tmp_path / "guides" / "nginx"
 +    chapters = guide / "chapters"
 +    chapters.mkdir(parents=True)
 +    security = chapters / "07-security.html"
 +    security.write_text("<html></html>\n")
 +    index = guide / "index.html"
 +    index.write_text(
 +        "\n".join(
 +            [
 +                "<ul>",
 +                '<li><a href="chapters/07-security.html">Chapter 7: Security</a></li>',
 +                "</ul>",
 +                "",
 +            ]
 +        )
 +    )
++
 +    result = validator.validate(
 +        "edit",
 +        {
 +            "file_path": str(index),
 +            "old_string": "</ul>",
 +            "new_string": (
 +                '<li><a href="chapters/07-security.html">Chapter 8: Performance</a></li>\n'
 +                '<li><a href="chapters/07-security.html">Chapter 9: SSL</a></li>\n'
 +                '<li><a href="chapters/07-security.html">Chapter 10: Monitoring</a></li>\n'
 +                "</ul>"
 +            ),
 +        },
 +    )
++
 +    assert result.valid is False
 +    assert (
 +        result.reason
 +        == "HTML root page repeats one local page as multiple distinct links"
 +    )
 +    assert "Do not inflate a root index or table of contents" in result.suggestion
 +    assert "chapters/07-security.html" in result.suggestion
++
++
  def test_pre_action_validator_blocks_shell_text_rewrite_for_html_target() -> None:
      validator = PreActionValidator()