chore: roadmap validator test 2

Author: fbarbu15

tools/roadmap_validator/identity.py

@@ -4,6 +4,7 @@
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
+from issues import ValidationIssue
 from paths import CONTENT_ROOT, should_skip
 
 IDENTIFIER_PATTERN = re.compile(r"^`([^`]+)`\s*$")
@@ -21,9 +22,9 @@ class CommitmentIdentity:
     expected_base: str
 
 
-def derive_identity(path: Path) -> Tuple[Optional[CommitmentIdentity], List[str]]:
+def derive_identity(path: Path) -> Tuple[Optional[CommitmentIdentity], List[ValidationIssue]]:
     """Infer roadmap identity metadata from the file path."""
-    issues: List[str] = []
+    issues: List[ValidationIssue] = []
     try:
         relative = path.resolve().relative_to(CONTENT_ROOT)
     except ValueError:
@@ -35,7 +36,11 @@ def derive_identity(path: Path) -> Tuple[Optional[CommitmentIdentity], List[str]
     match = FILENAME_PATTERN.match(path.stem)
     if not match:
         issues.append(
-            f"{path}: filename should follow `<year>q<quarter>-<slug>.md` (found `{path.name}`)"
+            ValidationIssue(
+                path=path,
+                line=None,
+                message=f"filename should follow `<year>q<quarter>-<slug>.md` (found `{path.name}`)",
+            )
         )
         return None, issues
 
@@ -44,18 +49,16 @@ def derive_identity(path: Path) -> Tuple[Optional[CommitmentIdentity], List[str]
     expected_base = f"vac:{unit}:{area}:{quarter}-{slug}"
     expected_tags = [quarter, unit, area]
     expected_identifier = expected_base
-    return (
-        CommitmentIdentity(
+    identity = CommitmentIdentity(
         unit=unit,
         quarter=quarter,
         area=area,
         slug=slug,
         expected_tags=expected_tags,
         expected_identifier=expected_identifier,
         expected_base=expected_base,
-    ),
-        issues,
     )
+    return identity, issues
 
 
 def validate_identity(
@@ -64,20 +67,28 @@ def validate_identity(
     lines: List[str],
     body_start: int,
     identity: CommitmentIdentity,
-) -> List[str]:
+) -> List[ValidationIssue]:
     """Validate tags and inline identifier for a commitment."""
-    issues: List[str] = []
+    issues: List[ValidationIssue] = []
 
     tags = front_matter.get("tags")
     if isinstance(tags, (list, tuple)):
         tag_values = [str(tag) for tag in tags]
         if tag_values != identity.expected_tags:
             issues.append(
-                f"{path}: tags should be {identity.expected_tags!r} (found {tag_values!r})"
+                ValidationIssue(
+                    path=path,
+                    line=1,
+                    message=f"tags should be {identity.expected_tags!r} (found {tag_values!r})",
+                )
             )
     else:
         issues.append(
-            f"{path}: tags must be a list matching {identity.expected_tags!r}"
+            ValidationIssue(
+                path=path,
+                line=1,
+                message=f"tags must be a list matching {identity.expected_tags!r}",
+            )
         )
 
     identifier_value: Optional[str] = None
@@ -92,13 +103,21 @@ def validate_identity(
 
     if identifier_value is None:
         issues.append(
-            f"{path}:{body_start + 1}: missing commitment identifier `"
-            f"{identity.expected_identifier}`"
+            ValidationIssue(
+                path=path,
+                line=body_start + 1,
+                message=f"missing commitment identifier `{identity.expected_identifier}`",
+            )
         )
     elif identifier_value != identity.expected_identifier:
         issues.append(
-            f"{path}:{identifier_line}: identifier should be `"
-            f"{identity.expected_identifier}` (found `{identifier_value}`)"
+            ValidationIssue(
+                path=path,
+                line=identifier_line,
+                message=(
+                    f"identifier should be `{identity.expected_identifier}` (found `{identifier_value}`)"
+                ),
+            )
         )
 
     return issues

tools/roadmap_validator/issues.py

@@ -0,0 +1,12 @@
+"""Validation issue data structures."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class ValidationIssue:
+    path: Path
+    line: Optional[int]
+    message: str

tools/roadmap_validator/tasks.py

@@ -17,7 +17,7 @@
 @dataclass
 class TaskIssue:
     message: str
-    line: int
+    line: Optional[int]
 
 
 @dataclass

tools/roadmap_validator/validate.py

@@ -5,11 +5,63 @@
 import os
 import shlex
 import sys
+from collections import defaultdict
+from pathlib import Path
 from typing import Iterable, List, Optional
-from paths import resolve_targets
+from paths import REPO_ROOT, resolve_targets
 from validator import validate_file
+from issues import ValidationIssue
 
-DEFAULT_TARGETS = "acz dst qa nes nim p2p rfc sc sec tke web"
+DEFAULT_TARGETS = "content"
+
+
+def _relpath(path: Path) -> Path:
+    if path.is_absolute():
+        try:
+            return path.relative_to(REPO_ROOT)
+        except ValueError:
+            return path
+    return path
+
+
+def format_issue(issue: ValidationIssue) -> str:
+    location = _relpath(issue.path)
+    prefix = f"{location}"
+    if issue.line:
+        prefix += f":{issue.line}"
+    return f"{prefix}: {issue.message}"
+
+
+def emit_github_annotations(issues: List[ValidationIssue]) -> None:
+    if os.getenv("GITHUB_ACTIONS") != "true":
+        return
+    for issue in issues:
+        location = _relpath(issue.path)
+        file_str = str(location)
+        if issue.line:
+            print(f"::error file={file_str},line={issue.line}::{issue.message}")
+        else:
+            print(f"::error file={file_str}::{issue.message}")
+
+    summary_path = os.getenv("GITHUB_STEP_SUMMARY")
+    if not summary_path:
+        return
+
+    issues_by_file = defaultdict(list)
+    for issue in issues:
+        issues_by_file[str(_relpath(issue.path))].append(issue)
+
+    unique_files = {str(_relpath(issue.path)) for issue in issues}
+
+    with open(summary_path, "a", encoding="utf-8") as summary:
+        summary.write("## Roadmap Validator Report\n\n")
+        summary.write(f"Found {len(issues)} issues across {len(unique_files)} file(s).\n\n")
+        for file_path, file_issues in sorted(issues_by_file.items()):
+            summary.write(f"- `{file_path}`\n")
+            for issue in file_issues:
+                line_info = f" (line {issue.line})" if issue.line else ""
+                summary.write(f"  - {issue.message}{line_info}\n")
+        summary.write("\n")
 
 
 def run_validator(targets: Iterable[str]) -> int:
@@ -18,13 +70,16 @@ def run_validator(targets: Iterable[str]) -> int:
         sys.stderr.write("No markdown files found for validation.\n")
         return 0
 
-    all_issues: List[str] = []
+    all_issues: List[ValidationIssue] = []
     for file_path in files:
         all_issues.extend(validate_file(file_path))
 
     if all_issues:
-        sys.stderr.write("\n".join(all_issues) + "\n")
-        sys.stderr.write(f"\nValidation failed for {len(files)} file(s).\n")
+        emit_github_annotations(all_issues)
+        for issue in sorted(all_issues, key=lambda i: (str(_relpath(i.path)), i.line or 0, i.message)):
+            print(format_issue(issue))
+        unique_files = { _relpath(i.path) for i in all_issues }
+        print(f"\nValidation failed for {len(unique_files)} file(s).")
         return 1
 
     print(f"All checks passed for {len(files)} file(s).")
@@ -38,7 +93,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "paths",
         nargs="*",
-        help="Files or directories to validate. Defaults to ROADMAP_VALIDATION_PATHS or 'qa'.",
+        help="Files or directories to validate. Defaults to ROADMAP_VALIDATION_PATHS or 'content'.",
     )
     return parser
 

tools/roadmap_validator/validator.py

@@ -7,6 +7,7 @@
 
 from constants import REQUIRED_FRONT_MATTER_KEYS
 from identity import derive_identity, validate_identity
+from issues import ValidationIssue
 from paths import should_skip
 from tasks import TaskReport, parse_tasks
 
@@ -30,13 +31,13 @@ def parse_front_matter(lines: List[str]) -> Tuple[dict, int]:
     return data, end_idx + 1
 
 
-def validate_front_matter(data: dict) -> List[str]:
-    issues: List[str] = []
+def validate_front_matter(path: Path, data: dict) -> List[ValidationIssue]:
+    issues: List[ValidationIssue] = []
     for key in REQUIRED_FRONT_MATTER_KEYS:
         if key not in data or data[key] in (None, "", []):
-            issues.append(f"missing `{key}` in front matter")
+            issues.append(ValidationIssue(path, 1, f"missing `{key}` in front matter"))
     if "tags" in data and not isinstance(data["tags"], (list, tuple)):
-        issues.append("`tags` must be a list")
+        issues.append(ValidationIssue(path, 1, "`tags` must be a list"))
     return issues
 
 
@@ -52,22 +53,20 @@ def find_task_section(lines: List[str], start: int) -> Optional[Tuple[int, int]]
     return None
 
 
-def validate_file(path: Path) -> List[str]:
+def validate_file(path: Path) -> List[ValidationIssue]:
     if should_skip(path):
         return []
 
     content = path.read_text(encoding="utf-8")
     lines = content.splitlines()
-    issues: List[str] = []
+    issues: List[ValidationIssue] = []
 
     try:
         front_matter, body_start = parse_front_matter(lines)
     except Exception as exc:  # pragma: no cover - defensive guard
-        return [f"{path}: failed to parse front matter: {exc}"]
+        return [ValidationIssue(path, 1, f"failed to parse front matter: {exc}")]
 
-    issues.extend(
-        f"{path}: {message}" for message in validate_front_matter(front_matter)
-    )
+    issues.extend(validate_front_matter(path, front_matter))
 
     identity, identity_issues = derive_identity(path)
     issues.extend(identity_issues)
@@ -81,16 +80,22 @@ def validate_file(path: Path) -> List[str]:
 
     section = find_task_section(lines, body_start)
     if not section:
-        issues.append(f"{path}: missing `## Task List` section")
+        issues.append(ValidationIssue(path, None, "missing `## Task List` section"))
         return issues
 
     start, end = section
     tasks: List[TaskReport] = parse_tasks(lines, start, end, expected_base)
     if not tasks:
-        issues.append(f"{path}: no tasks found under `## Task List`")
+        issues.append(ValidationIssue(path, None, "no tasks found under `## Task List`"))
         return issues
 
     for task in tasks:
-        for issue in task.issues:
-            issues.append(f"{path}:{issue.line}: Task `{task.name}` {issue.message}")
+        for task_issue in task.issues:
+            issues.append(
+                ValidationIssue(
+                    path=path,
+                    line=task_issue.line,
+                    message=f"Task `{task.name}` {task_issue.message}",
+                )
+            )
     return issues