From 7c0c6c2057b1a7f2c908f390a599ab99999bac70 Mon Sep 17 00:00:00 2001 From: M34nX Date: Wed, 18 Nov 2026 03:34:28 +0330 Subject: [PATCH 1/3] test: add unit coverage for Markdown link validation --- tests/test_validate_structure.py | 80 ++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 tests/test_validate_structure.py diff --git a/tests/test_validate_structure.py b/tests/test_validate_structure.py new file mode 100644 index 0000000..f7a2251 --- /dev/null +++ b/tests/test_validate_structure.py @@ -0,0 +1,80 @@ +"""Unit tests for the repository's Markdown-link validator.""" + +from pathlib import Path +import tempfile +import unittest + +from scripts import validate_structure as validator + + +class InternalMarkdownLinkTests(unittest.TestCase): + def setUp(self) -> None: + self.temp_dir = tempfile.TemporaryDirectory() + self.root = Path(self.temp_dir.name) + self.original_root = validator.ROOT + self.original_errors = validator.ERRORS + validator.ROOT = self.root + validator.ERRORS = [] + + def tearDown(self) -> None: + validator.ROOT = self.original_root + validator.ERRORS = self.original_errors + self.temp_dir.cleanup() + + def write(self, relative_path: str, content: str = "") -> Path: + path = self.root / relative_path + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + return path + + def test_valid_relative_file_link(self) -> None: + self.write("README.md", "[Guide](docs/guide.md)\n") + self.write("docs/guide.md", "# Guide\n") + + checked = validator.validate_internal_links() + + self.assertEqual(checked, 1) + self.assertEqual(validator.ERRORS, []) + + def test_directory_link_resolves_to_readme(self) -> None: + self.write("README.md", "[Docs](docs/)\n") + self.write("docs/README.md", "# Documentation\n") + + checked = validator.validate_internal_links() + + self.assertEqual(checked, 1) + self.assertEqual(validator.ERRORS, []) + + def test_broken_internal_link_is_reported(self) -> None: + self.write("README.md", "[Missing](docs/missing.md)\n") + + checked = validator.validate_internal_links() + + self.assertEqual(checked, 1) + self.assertTrue(any("Broken internal link" in error for error in validator.ERRORS)) + + def test_links_cannot_escape_repository_root(self) -> None: + self.write("docs/page.md", "[Outside](../../outside.md)\n") + + checked = validator.validate_internal_links() + + self.assertEqual(checked, 0) + self.assertTrue( + any("Internal link escapes repository" in error for error in validator.ERRORS) + ) + + def test_external_anchor_and_fenced_code_links_are_ignored(self) -> None: + self.write( + "README.md", + "[External](https://example.com) [Anchor](#section)\n" + "\n```md\n[Example](missing.md)\n```\n", + ) + + checked = validator.validate_internal_links() + + self.assertEqual(checked, 0) + self.assertEqual(validator.ERRORS, []) + + +if __name__ == "__main__": + unittest.main() From 28373bdc28579652cf3ac7c4b635740d643543df Mon Sep 17 00:00:00 2001 From: M34nX Date: Wed, 18 Nov 2026 03:34:30 +0330 Subject: [PATCH 2/3] ci: run validator unit tests before structural checks --- .github/workflows/validate-structure.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/validate-structure.yml b/.github/workflows/validate-structure.yml index bad8193..bcffed2 100644 --- a/.github/workflows/validate-structure.yml +++ b/.github/workflows/validate-structure.yml @@ -21,5 +21,7 @@ jobs: run: python --version - name: Install validation dependencies run: python -m pip install -r requirements-dev.txt + - name: Run validator unit tests + run: python -m unittest discover -s tests -p 'test_*.py' - name: Validate repository run: python scripts/validate_structure.py From 6b96f5e6e20e7d87e34fd646433801bd704c74a4 Mon Sep 17 00:00:00 2001 From: M34nX Date: Wed, 18 Nov 2026 03:34:32 +0330 Subject: [PATCH 3/3] docs: document validator unit test workflow --- tests/README.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/tests/README.md b/tests/README.md index aa33e69..8caa58f 100644 --- a/tests/README.md +++ b/tests/README.md @@ -2,16 +2,27 @@ Tests protect content integrity, not merely application behaviour. -## Automated checks currently run in GitHub Actions +## Run locally -Run locally: - -``` +```bash python -m pip install -r requirements-dev.txt +python -m unittest discover -s tests -p 'test_*.py' python scripts/validate_structure.py ``` -The validator currently checks: +## Automated checks + +GitHub Actions runs the validator unit tests before the repository-wide structural validation. + +The unit tests currently cover Markdown-link validation: + +- Valid relative file links. +- Directory links resolving to `README.md`. +- Broken internal links. +- Links that attempt to escape the repository root. +- External links, fragment-only links, and links inside fenced code blocks. + +The repository validator checks: - YAML registry and knowledge-graph files parse successfully. - All seven JSON Schemas are valid JSON Schema Draft 2020-12 documents.