крупное обновление документации

2026-07-10 18:15:05 +04:00
parent 01953cc25e
commit 0eef72a2c2
28 changed files with 2435 additions and 6 deletions
@@ -0,0 +1,101 @@
+param(
+    [string]$Root = (Split-Path -Parent $PSScriptRoot)
+)
+
+$ErrorActionPreference = 'Stop'
+$failures = [System.Collections.Generic.List[string]]::new()
+
+$requiredFiles = @(
+    'AGENTS.md',
+    'docs\README.md',
+    'docs\DOCUMENTATION_STANDARD.md',
+    'docs\modules\README.md',
+    'docs\modules\TEMPLATE.md',
+    'targets\DEVELOPMENT_ROADMAP.md'
+)
+
+foreach ($relative in $requiredFiles) {
+    if (-not (Test-Path -LiteralPath (Join-Path $Root $relative))) {
+        $failures.Add("Missing required documentation file: $relative")
+    }
+}
+
+$agentGuide = Join-Path $Root 'AGENTS.md'
+if (Test-Path -LiteralPath $agentGuide) {
+    $agentContent = Get-Content -Raw -Encoding UTF8 -LiteralPath $agentGuide
+    if ($agentContent -notmatch 'DOCUMENTATION_STANDARD\.md') {
+        $failures.Add('AGENTS.md does not reference docs/DOCUMENTATION_STANDARD.md')
+    }
+}
+
+$requiredHeadings = @(
+    '## Metadata',
+    '## Purpose',
+    '## Non-goals',
+    '## Context and boundaries',
+    '## Public API',
+    '## Inputs and outputs',
+    '## Data flow',
+    '## Ownership, threading and resources',
+    '## Errors, cancellation and recovery',
+    '## Verification',
+    '## Known gaps and risks',
+    '## Source map'
+)
+
+$modulesDir = Join-Path $Root 'docs\modules'
+$moduleCount = 0
+if (Test-Path -LiteralPath $modulesDir) {
+    $moduleFiles = Get-ChildItem -LiteralPath $modulesDir -Filter '*.md' -File |
+        Where-Object { $_.Name -notin @('README.md', 'TEMPLATE.md') }
+    foreach ($file in $moduleFiles) {
+        ++$moduleCount
+        $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+        foreach ($heading in $requiredHeadings) {
+            if (-not $content.Contains($heading)) {
+                $failures.Add("docs/modules/$($file.Name): missing heading '$heading'")
+            }
+        }
+        if ($content -notmatch '(?s)```mermaid\s+flowchart') {
+            $failures.Add("docs/modules/$($file.Name): missing Mermaid data-flow diagram")
+        }
+        if ($content -notmatch '\| Status \|') {
+            $failures.Add("docs/modules/$($file.Name): missing Status metadata")
+        }
+        if ($content -notmatch '\| Last verified \|') {
+            $failures.Add("docs/modules/$($file.Name): missing Last verified metadata")
+        }
+    }
+}
+
+$documentationRoots = @('docs', 'targets', 'coordination')
+foreach ($relativeRoot in $documentationRoots) {
+    $path = Join-Path $Root $relativeRoot
+    if (-not (Test-Path -LiteralPath $path)) {
+        continue
+    }
+    foreach ($file in Get-ChildItem -LiteralPath $path -Recurse -Filter '*.md' -File) {
+        $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+        foreach ($match in [regex]::Matches($content, '\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)')) {
+            $target = $match.Groups[1].Value
+            if ($target -match '^(https?:|mailto:)') {
+                continue
+            }
+            $resolved = Join-Path $file.DirectoryName $target
+            if (-not (Test-Path -LiteralPath $resolved)) {
+                $relativeFile = Resolve-Path -LiteralPath $file.FullName -Relative
+                $failures.Add("$relativeFile`: broken relative link '$target'")
+            }
+        }
+    }
+}
+
+if ($failures.Count -gt 0) {
+    foreach ($failure in $failures) {
+        Write-Error $failure
+    }
+    exit 1
+}
+
+Write-Output "Documentation check passed: module_specs=$moduleCount required_files=$($requiredFiles.Count)"
+exit 0