fix: apply review feedback — fence exclusion for inline backticks, relative path exclusion in frontmatter validator, fix deprecated test, update README

- markdown_parser.py: also skip inline-backtick path extraction inside fenced code blocks
  (previously only link patterns were skipped inside fences)
- validate-frontmatter.py: use relative_to(docs_root).parts for directory exclusions
  so running the validator directly on .test-fixtures/ no longer skips everything
- test_frontmatter_validator.py: fix test_deprecated_without_superseded_by_warns —
  deprecated-date was appended after the document body (outside YAML), now correctly
  placed inside the frontmatter block; add test_validate_fixtures_directly
- test_markdown_parser.py: add test_inline_backtick_path_in_fenced_block_excluded
- docs/.test-fixtures/README.md: replace misleading direct-invocation example
  with pytest commands

Co-authored-by: efargas <9705611+efargas@users.noreply.github.com>
Agent-Logs-Url: https://github.com/efargas/S7-Tools/sessions/aeb37029-8f66-4521-b16b-8f013b6abd02

Author: Copilot

docs/.test-fixtures/README.md

@@ -16,13 +16,14 @@ This directory contains markdown files used to test and validate the
 ## Usage
 
 ```bash
-# Validate frontmatter only
-python scripts/validate-frontmatter.py docs/.test-fixtures/
+# Run frontmatter-specific tests
+pytest scripts/tests -k frontmatter -q
 
-# Run full validation suite (skip-compilation for speed)
-python scripts/validate-documentation.py --skip-compilation --verbose
+# Run the full validation test suite (covers all fixture scenarios)
+pytest scripts/tests -q
 ```
 
 > **Note:** This directory is excluded from the production validation runs
-> (`validate-frontmatter.py` and `validate-documentation.py` both skip `.test-fixtures/`).
-> Use the test suite in `scripts/tests/` to exercise these fixtures programmatically.
+> (`validate-frontmatter.py` and `validate-documentation.py` both skip `.test-fixtures/`
+> when scanning the main docs tree).  Use the pytest suite above to exercise these
+> fixtures programmatically.

scripts/extractors/markdown_parser.py

@@ -151,7 +151,12 @@ def extract_file_references(self, content: str, source_file: str) -> list[FilePa
                 in_code_fence = not in_code_fence
                 continue
 
-            # Always extract inline backtick patterns (safe – content is inside backticks)
+            # Skip all extraction while inside a fenced code block –
+            # paths and links there are illustrative/hypothetical, not real refs.
+            if in_code_fence:
+                continue
+
+            # Extract inline backtick patterns (prose references)
             for pattern in inline_patterns:
                 for match in re.finditer(pattern, line):
                     referenced_path = match.group(1)
@@ -166,23 +171,22 @@ def extract_file_references(self, content: str, source_file: str) -> list[FilePa
                         exists=False
                     ))
 
-            # Only extract link patterns outside fenced code blocks
-            if not in_code_fence:
-                # Temporarily remove inline code spans to avoid matching inside them
-                line_no_inline = re.sub(r'`[^`]+`', '', line)
-                for pattern in link_patterns:
-                    for match in re.finditer(pattern, line_no_inline):
-                        referenced_path = match.group(1)
-                        path_type = "relative" if referenced_path.startswith('../') else (
-                            "absolute" if referenced_path.startswith('/') else "project_relative"
-                        )
-                        references.append(FilePathReference(
-                            source_file=source_file,
-                            line_number=line_num,
-                            referenced_path=referenced_path,
-                            path_type=path_type,
-                            exists=False
-                        ))
+            # Extract link patterns; strip inline code spans first to avoid
+            # matching syntax written inside backticks.
+            line_no_inline = re.sub(r'`[^`]+`', '', line)
+            for pattern in link_patterns:
+                for match in re.finditer(pattern, line_no_inline):
+                    referenced_path = match.group(1)
+                    path_type = "relative" if referenced_path.startswith('../') else (
+                        "absolute" if referenced_path.startswith('/') else "project_relative"
+                    )
+                    references.append(FilePathReference(
+                        source_file=source_file,
+                        line_number=line_num,
+                        referenced_path=referenced_path,
+                        path_type=path_type,
+                        exists=False
+                    ))
 
         return references
 

scripts/tests/test_frontmatter_validator.py

@@ -157,7 +157,7 @@ def test_metadata_directory_excluded(self, tmp_path):
         assert v.summary.errors == 0
 
     def test_test_fixtures_directory_excluded(self, tmp_path):
-        """Files under docs/.test-fixtures/ must be skipped."""
+        """Files under docs/.test-fixtures/ must be skipped when scanning the full docs tree."""
         docs = _make_docs(tmp_path, {
             ".test-fixtures/fixture.md": "# Fixture\n\nNo frontmatter.\n",
             "guides/valid.md": VALID_FM,
@@ -167,6 +167,20 @@ def test_test_fixtures_directory_excluded(self, tmp_path):
         assert v.summary.files_checked == 1
         assert v.summary.errors == 0
 
+    def test_validate_fixtures_directly(self, tmp_path):
+        """Running the validator directly on .test-fixtures/ must check the files it contains,
+        not skip them (regression test for absolute-path parts check).
+        """
+        fixtures = tmp_path / ".test-fixtures"
+        fixtures.mkdir()
+        (fixtures / "fixture.md").write_text(VALID_FM, encoding="utf-8")
+
+        v = FrontmatterValidator(str(fixtures))
+        v.validate_all()
+        # The file should be checked (not skipped because '.test-fixtures' is in its absolute path)
+        assert v.summary.files_checked == 1
+        assert v.summary.errors == 0
+
 
 class TestFrontmatterDeprecatedDocuments:
     """Tests for deprecated document validation rules."""
@@ -184,8 +198,8 @@ def test_deprecated_without_superseded_by_warns(self, tmp_path):
         """Deprecated documents without superseded-by should produce META-008 warning."""
         content = VALID_FM.replace(
             'status: "current"',
-            'status: "deprecated"'
-        ) + "deprecated-date: \"2026-01-01\"\n"
+            'status: "deprecated"\ndeprecated-date: "2026-01-01"'
+        )
         docs = _make_docs(tmp_path, {"guides/dep2.md": content})
         v = FrontmatterValidator(str(docs))
         v.validate_all()

scripts/tests/test_markdown_parser.py

@@ -371,5 +371,26 @@ def test_four_backtick_fence_handled(self):
         assert "src/Does/Not/Exist.cs" not in paths
 
 
+    def test_inline_backtick_path_in_fenced_block_excluded(self):
+        """Inline-backtick paths that appear inside a fenced code block (e.g. a markdown
+        example showing how to write a reference) must NOT be extracted as real file
+        references.
+        """
+        content = """\
+```markdown
+Here is how you reference a file: `src/S7Tools/Hypothetical/MyService.cs`
+```
+
+Real reference: `src/S7Tools/Services/Profiles/StandardProfileManager.cs`
+"""
+        references = extract_file_references(content, "test.md")
+        paths = [r.referenced_path for r in references]
+
+        # Path inside the fenced block must NOT be captured
+        assert "src/S7Tools/Hypothetical/MyService.cs" not in paths
+        # Prose path after the block must be captured
+        assert "src/S7Tools/Services/Profiles/StandardProfileManager.cs" in paths
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

scripts/validate-frontmatter.py

@@ -68,11 +68,19 @@ def __init__(self, docs_root: str, strict: bool = False):
     def validate_all(self):
         """Validate all markdown files in docs_root"""
         for md_file in self.docs_root.rglob('*.md'):
-            # Skip metadata, test fixtures, and website/blog directories
+            # Compute path relative to docs_root so that exclusions only apply
+            # when the excluded directory is *under* docs_root, not when the
+            # script is invoked directly on one of those subdirectories.
+            try:
+                relative_parts = md_file.relative_to(self.docs_root).parts
+            except ValueError:
+                # Fallback: file is not under docs_root (shouldn't happen with rglob)
+                relative_parts = md_file.parts
+
             if (
-                '.metadata' in md_file.parts or
-                '.test-fixtures' in md_file.parts or
-                'website' in md_file.parts
+                '.metadata' in relative_parts or
+                '.test-fixtures' in relative_parts or
+                'website' in relative_parts
             ):
                 continue