chore: roadmap validator draft 2

Author: fbarbu15

.github/workflows/roadmap-validator.yml

@@ -1,26 +1,34 @@
 name: Roadmap Validator
 
 on:
-  pull_request:
-    paths:
-      - 'content/qa/**'
-      - 'tools/roadmap_validator/validate.py'
-      - 'tools/roadmap_validator/**'
-      - '.github/workflows/roadmap-validator.yml'
+  workflow_dispatch:
+    inputs:
+      paths:
+        description: 'Space-separated paths or directories to validate'
+        required: false
+        default: ''
   push:
     branches:
       - main
+      - chore/roadmap-validator
     paths:
+      - 'content/acz/**'
+      - 'content/dst/**'
       - 'content/qa/**'
-      - 'tools/roadmap_validator/validate.py'
+      - 'content/nes/**'
+      - 'content/nim/**'
+      - 'content/p2p/**'
+      - 'content/rfc/**'
+      - 'content/sc/**'
+      - 'content/sec/**'
+      - 'content/tke/**'
+      - 'content/web/**'
       - 'tools/roadmap_validator/**'
       - '.github/workflows/roadmap-validator.yml'
 
 jobs:
   validate:
     runs-on: ubuntu-latest
-    env:
-      TARGET_DIRECTORIES: "content/qa"
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -35,33 +43,28 @@ jobs:
       - name: Install dependencies
         run: pip install --disable-pip-version-check --no-cache-dir pyyaml
 
+      - name: Detect changed markdown files
+        if: ${{ github.event_name != 'workflow_dispatch' }}
+        id: changed-files
+        uses: tj-actions/changed-files@v42
+        with:
+          files: |
+            **/*.md
+
       - name: Run roadmap validator
         run: |
           set -eo pipefail
-          BASE_SHA="${{ github.event.pull_request.base.sha || github.event.before }}"
-          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
-            CHANGED_FILES=$(git ls-files)
-          else
-            CHANGED_FILES=$(git diff --name-only --diff-filter=ACMRT "$BASE_SHA" "$GITHUB_SHA")
-          fi
 
-          TARGET_FILES=""
-          for file in $CHANGED_FILES; do
-            for dir in $TARGET_DIRECTORIES; do
-              case "$file" in
-                $dir/*.md)
-                  if [ -f "$file" ]; then
-                    TARGET_FILES="$TARGET_FILES $file"
-                  fi
-                  ;;
-              esac
-            done
-          done
-
-          if [ -z "$TARGET_FILES" ]; then
-            echo "No roadmap markdown changes detected."
-            exit 0
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TARGETS="${{ github.event.inputs.paths }}"
+          else
+            TARGETS="${{ steps.changed-files.outputs.all_changed_files }}"
+            if [ -z "$TARGETS" ]; then
+              echo "No roadmap markdown changes detected."
+              exit 0
+            fi
           fi
 
-          echo "Validating files:$TARGET_FILES"
-          python tools/roadmap_validator/validate.py $TARGET_FILES
+          echo "Validating targets:"
+          printf '%s\n' $TARGETS
+          python tools/roadmap_validator/validate.py $TARGETS

tools/roadmap_validator/constants.py

@@ -68,16 +68,3 @@
 )
 
 DEFAULT_SKIP_FILENAMES = {"index.md"}
-
-__all__ = [
-    "REQUIRED_FRONT_MATTER_KEYS",
-    "REQUIRED_TASK_FIELDS",
-    "METADATA_ALIAS_MAP",
-    "DATE_RE",
-    "TODO_RE",
-    "TASK_HEADING_RE",
-    "META_LINE_RE",
-    "VAGUE_KEYWORDS",
-    "TANGIBLE_KEYWORDS",
-    "DEFAULT_SKIP_FILENAMES",
-]

tools/roadmap_validator/identity.py

@@ -3,9 +3,8 @@
 import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Dict, List, Optional
-
-from .paths import CONTENT_ROOT, should_skip
+from typing import Dict, List, Optional, Tuple
+from paths import CONTENT_ROOT, should_skip
 
 IDENTIFIER_PATTERN = re.compile(r"^`([^`]+)`\s*$")
 FILENAME_PATTERN = re.compile(r"^(?P<quarter>\d{4}q[1-4])-(?P<slug>.+)$")
@@ -22,33 +21,40 @@ class CommitmentIdentity:
     expected_base: str
 
 
-def derive_identity(path: Path) -> Optional[CommitmentIdentity]:
+def derive_identity(path: Path) -> Tuple[Optional[CommitmentIdentity], List[str]]:
     """Infer roadmap identity metadata from the file path."""
+    issues: List[str] = []
     try:
         relative = path.resolve().relative_to(CONTENT_ROOT)
     except ValueError:
-        return None
+        return None, issues
     if len(relative.parts) < 3 or should_skip(path):
-        return None
+        return None, issues
 
     unit, area = relative.parts[0], relative.parts[1]
     match = FILENAME_PATTERN.match(path.stem)
     if not match:
-        return None
+        issues.append(
+            f"{path}: filename should follow `<year>q<quarter>-<slug>.md` (found `{path.name}`)"
+        )
+        return None, issues
 
     quarter = match.group("quarter")
     slug = match.group("slug")
     expected_base = f"vac:{unit}:{area}:{quarter}-{slug}"
     expected_tags = [quarter, unit, area]
     expected_identifier = expected_base
-    return CommitmentIdentity(
+    return (
+        CommitmentIdentity(
         unit=unit,
         quarter=quarter,
         area=area,
         slug=slug,
         expected_tags=expected_tags,
         expected_identifier=expected_identifier,
         expected_base=expected_base,
+    ),
+        issues,
     )
 
 
@@ -96,6 +102,3 @@ def validate_identity(
         )
 
     return issues
-
-
-__all__ = ["CommitmentIdentity", "derive_identity", "validate_identity"]

tools/roadmap_validator/paths.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 from typing import Iterable, List, Optional
 
-from .constants import DEFAULT_SKIP_FILENAMES
+from constants import DEFAULT_SKIP_FILENAMES
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 CONTENT_ROOT = REPO_ROOT / "content"
@@ -63,11 +63,3 @@ def resolve_targets(targets: Iterable[str]) -> List[Path]:
         else:
             sys.stderr.write(f"Warning: skipping non-markdown path {raw_target!r}\n")
     return md_files
-
-
-__all__ = [
-    "CONTENT_ROOT",
-    "REPO_ROOT",
-    "should_skip",
-    "resolve_targets",
-]

tools/roadmap_validator/tasks.py

@@ -2,8 +2,7 @@
 
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional, Tuple
-
-from .constants import (
+from constants import (
     DATE_RE,
     META_LINE_RE,
     METADATA_ALIAS_MAP,
@@ -193,6 +192,3 @@ def flush_current() -> None:
 
     flush_current()
     return tasks
-
-
-__all__ = ["TaskIssue", "TaskReport", "parse_tasks"]

tools/roadmap_validator/validate.py

@@ -5,18 +5,11 @@
 import os
 import shlex
 import sys
-from pathlib import Path
 from typing import Iterable, List, Optional
+from paths import resolve_targets
+from validator import validate_file
 
-if __package__ is None or __package__ == "":
-    sys.path.append(str(Path(__file__).resolve().parent.parent.parent))
-    from tools.roadmap_validator.paths import resolve_targets
-    from tools.roadmap_validator.validator import validate_file
-else:
-    from .paths import resolve_targets
-    from .validator import validate_file
-
-DEFAULT_TARGETS = "qa"
+DEFAULT_TARGETS = "acz dst qa nes nim p2p rfc sc sec tke web"
 
 
 def run_validator(targets: Iterable[str]) -> int:

tools/roadmap_validator/validator.py

@@ -5,10 +5,10 @@
 
 import yaml
 
-from .constants import REQUIRED_FRONT_MATTER_KEYS
-from .identity import derive_identity, validate_identity
-from .paths import should_skip
-from .tasks import TaskReport, parse_tasks
+from constants import REQUIRED_FRONT_MATTER_KEYS
+from identity import derive_identity, validate_identity
+from paths import should_skip
+from tasks import TaskReport, parse_tasks
 
 
 def parse_front_matter(lines: List[str]) -> Tuple[dict, int]:
@@ -69,7 +69,9 @@ def validate_file(path: Path) -> List[str]:
         f"{path}: {message}" for message in validate_front_matter(front_matter)
     )
 
-    identity = derive_identity(path)
+    identity, identity_issues = derive_identity(path)
+    issues.extend(identity_issues)
+
     expected_base = None
     if identity:
         issues.extend(
@@ -92,6 +94,3 @@ def validate_file(path: Path) -> List[str]:
         for issue in task.issues:
             issues.append(f"{path}:{issue.line}: Task `{task.name}` {issue.message}")
     return issues
-
-
-__all__ = ["validate_file"]