Merge pull request #160 from efargas/copilot/audit-refactor-codebase

Architectural canon docs, missing appsettings.json, and documentation validation scripts

Author: efargas

docs/.test-fixtures/README.md

@@ -0,0 +1,29 @@
+# Documentation Validation Test Fixtures
+
+This directory contains markdown files used to test and validate the
+`scripts/validate-*.py` validation suite.
+
+## Structure
+
+| File | Purpose |
+|------|---------|
+| `valid-document.md` | Well-formed document: correct frontmatter, valid file refs, valid links |
+| `invalid-frontmatter.md` | Missing / malformed frontmatter fields |
+| `code-blocks.md` | Code blocks with escape chars, inline code, fenced fences |
+| `links.md` | Mix of valid, broken, external, anchor, and code-block links |
+| `file-references.md` | Mix of existing and missing file path references |
+
+## Usage
+
+```bash
+# Run frontmatter-specific tests
+pytest scripts/tests -k frontmatter -q
+
+# 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/`
+> when scanning the main docs tree).  Use the pytest suite above to exercise these
+> fixtures programmatically.

docs/.test-fixtures/code-blocks.md

@@ -0,0 +1,82 @@
+---
+title: "Code Blocks Test"
+version: "1.0.0"
+created: "2026-01-01"
+last-updated: "2026-03-24"
+status: "current"
+tags: ["test", "code-blocks", "escape-chars"]
+---
+
+# Code Blocks Test
+
+This document exercises escape-character and code-block edge cases that
+the validation scripts must handle without false positives.
+
+## Fenced Code Blocks — No False Links
+
+The VB.NET snippet below calls `_random.[Next](0, count)`, which looks like a
+markdown link `](0, count)` if the code fence is not properly detected.
+
+```vbnet
+Private Function GenerateIndex() As Integer
+    Dim index As Integer = _random.[Next](0, _eventNames.Count)
+    Return _messages(_random.[Next](0, _messages.Count))
+End Function
+```
+
+A C# snippet with square-bracket indexers:
+
+```csharp
+var result = myList[index].ToString();
+var nested = dict["key"][0];
+int[] arr = new int[items.Count];
+```
+
+The paths below are inside a fenced block and must **not** be extracted as
+file references (they are hypothetical examples, not real paths):
+
+```text
+src/Does/Not/Exist.cs
+docs/imaginary/file.md
+tests/NonExistent/Test.cs
+```
+
+## Inline Code — Safe Backtick Paths
+
+These inline code paths **should** be extracted because they appear in prose:
+
+- `src/S7Tools/Services/Profiles/StandardProfileManager.cs`
+
+## Escaped Markdown Characters
+
+The following use backslash escapes and must not trigger validators:
+
+\[this is not a link\](not-a-target.md)
+\`not inline code\`
+
+## Mixed Fences
+
+Opening fence with extra backticks should be matched correctly:
+
+````markdown
+This is a code block with four backticks.
+](docs/fake-link.md)
+src/Fake/File.cs
+````
+
+## Tildes as Fences
+
+~~~python
+def method(self, arg):
+    return self.items[index](0, len(self.items))
+~~~
+
+## Nested Code in Lists
+
+- Item with `src/S7Tools/Services/Tasking/ResourceCoordinator.cs` inline ref.
+- Item without any code.
+
+## Links Inside Code Spans
+
+The text `[not a link](not-a-file.md)` written inside backticks should NOT
+produce a broken-link error.

docs/.test-fixtures/file-references.md

@@ -0,0 +1,43 @@
+---
+title: "File References Test"
+version: "1.0.0"
+created: "2026-01-01"
+last-updated: "2026-03-24"
+status: "current"
+tags: ["test", "file-references"]
+---
+
+# File References Test
+
+This document exercises file-reference extraction and resolution.
+
+## Existing References (should all resolve)
+
+Inline backtick paths that exist in the repository:
+
+- `src/S7Tools/Services/Profiles/StandardProfileManager.cs`
+- `src/S7Tools.Core/Interfaces/Services/IProfileManager.cs`
+- `src/S7Tools.Core/Interfaces/Services/IProfileBase.cs`
+- `src/S7Tools/Services/Socat/SocatService.cs`
+- `src/S7Tools/Services/PowerSupply/PowerSupplyService.cs`
+- `src/S7Tools/Services/Tasking/ResourceCoordinator.cs`
+
+## Paths Inside Code Blocks (must NOT be extracted as file references)
+
+The paths inside the fenced block below are hypothetical examples and should
+not be counted as file references by the validator:
+
+```text
+src/Does/Not/Exist.cs
+docs/imaginary-file.md
+tests/Fake/FakeTest.cs
+src/S7Tools/Hypothetical/MyService.cs
+```
+
+## Relative Markdown Links
+
+Link to sibling: [valid document](valid-document.md)
+
+## Path in Markdown Link Syntax
+
+[StandardProfileManager](../../src/S7Tools/Services/Profiles/StandardProfileManager.cs)

docs/.test-fixtures/invalid-frontmatter.md

@@ -0,0 +1,22 @@
+---
+title: "Invalid Frontmatter Test"
+version: "not-semver"
+created: "01/01/2026"
+status: "unknown-status"
+tags: []
+---
+
+# Invalid Frontmatter Test
+
+This document deliberately contains frontmatter violations so the validator
+can be tested against known-bad input.
+
+## Expected Violations
+
+| Rule | Field | Problem |
+|------|-------|---------|
+| META-002 | version | `not-semver` is not valid semver (expects `X.Y.Z`) |
+| META-003 | created | `01/01/2026` is not `YYYY-MM-DD` format |
+| META-001 | last-updated | Field is missing entirely |
+| META-004 | status | `unknown-status` is not a recognised status value |
+| META-005 | tags | Empty array is not allowed |

docs/.test-fixtures/links.md

@@ -0,0 +1,53 @@
+---
+title: "Links Test"
+version: "1.0.0"
+created: "2026-01-01"
+last-updated: "2026-03-24"
+status: "current"
+tags: ["test", "links"]
+---
+
+# Links Test
+
+This document exercises link-extraction edge cases for the link validator.
+
+## Valid Internal Links
+
+- Sibling: [valid-document](valid-document.md)
+- Another sibling: [code-blocks](code-blocks.md)
+
+## Anchor-Only Links (must not trigger broken-link errors)
+
+- [Jump to section](#valid-internal-links)
+- [Another anchor](#code-snippets-in-links)
+
+## External Links (must be ignored by the internal-link validator)
+
+- [GitHub](https://github.com/efargas/S7-Tools)
+- [Avalonia UI](https://avaloniaui.net)
+- [Microsoft Docs](https://docs.microsoft.com)
+
+## Links with Anchors (file must exist, anchor is informational)
+
+- [valid doc section](valid-document.md#file-references)
+
+## Code Snippets in Links
+
+Links written **inside** backticks must not be treated as real links:
+
+The text `` [not a link](no-such-file.md) `` is inline code, not a link.
+
+And inside a fenced block they must also be ignored:
+
+```markdown
+[fake link inside fence](totally-imaginary.md)
+```
+
+## Link with URL-Encoded Characters
+
+- [url encoded](valid-document.md)
+
+## mailto and Protocol Links (must be ignored)
+
+- [Send email](mailto:user@example.com)
+- [FTP resource](ftp://example.com/resource)

docs/.test-fixtures/valid-document.md

@@ -0,0 +1,59 @@
+---
+title: "Valid Test Document"
+version: "1.0.0"
+created: "2026-01-01"
+last-updated: "2026-03-24"
+status: "current"
+tags: ["test", "fixture", "validation"]
+---
+
+# Valid Test Document
+
+This document has correct frontmatter and is used to verify that the
+validation scripts correctly accept well-formed documentation.
+
+## File References
+
+The following file references exist in the repository and should all resolve:
+
+- `src/S7Tools/Services/Profiles/StandardProfileManager.cs`
+- `src/S7Tools.Core/Interfaces/Services/IProfileManager.cs`
+- `src/S7Tools.Core/Interfaces/Services/IProfileBase.cs`
+- `src/S7Tools/Services/Socat/SocatService.cs`
+- `src/S7Tools/Services/PowerSupply/PowerSupplyService.cs`
+- `src/S7Tools/Services/Tasking/ResourceCoordinator.cs`
+
+## Code Snippets
+
+C# code inside fenced blocks must **not** generate false-positive file references
+or link targets.
+
+```csharp
+// Correct: StandardProfileManager implements the unified pattern
+public class MyProfileService : StandardProfileManager<MyProfile>
+{
+    protected override MyProfile CreateDefaultProfile() =>
+        new() { Name = "Default" };
+}
+```
+
+Inline code like `src/S7Tools/Services/Profiles/StandardProfileManager.cs` is fine
+because the validator intentionally resolves inline-backtick paths.
+
+```csharp
+// This is a simplified illustration
+// ... simplified
+public class SimplifiedExample
+{
+    // work omitted for brevity
+}
+```
+
+## Internal Links
+
+Link to a sibling fixture: [invalid-frontmatter](invalid-frontmatter.md)
+
+## Escaped Characters
+
+Markdown allows escape sequences: \*not bold\*, \[not a link\], \`not code\`.
+These must not be mistaken for real syntax by the validators.