chore: roadmap validator draft

Author: fbarbu15

.github/workflows/roadmap-validator.yml

@@ -0,0 +1,67 @@
+name: Roadmap Validator
+
+on:
+  pull_request:
+    paths:
+      - 'content/qa/**'
+      - 'tools/roadmap_validator/validate.py'
+      - 'tools/roadmap_validator/**'
+      - '.github/workflows/roadmap-validator.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'content/qa/**'
+      - 'tools/roadmap_validator/validate.py'
+      - '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
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: pip install --disable-pip-version-check --no-cache-dir pyyaml
+
+      - 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
+          fi
+
+          echo "Validating files:$TARGET_FILES"
+          python tools/roadmap_validator/validate.py $TARGET_FILES

.gitignore

@@ -8,4 +8,6 @@ private/
 .replit
 replit.nix
 node_modules
-.ipynb_checkpoints/
+.ipynb_checkpoints/
+.cache
+__pycache__

tools/roadmap_validator/__init__.py

@@ -0,0 +1,5 @@
+"""Roadmap validator library."""
+
+from .validate import main, run_validator
+
+__all__ = ["main", "run_validator"]

tools/roadmap_validator/constants.py

@@ -0,0 +1,83 @@
+"""Shared constants and regular expressions for roadmap validation."""
+
+import re
+
+REQUIRED_FRONT_MATTER_KEYS = ("title", "tags", "description")
+REQUIRED_TASK_FIELDS = ("owner", "status", "start-date", "end-date")
+
+METADATA_ALIAS_MAP = {
+    "fully-qualified-name": "fully-qualified-name",
+    "fully qualified name": "fully-qualified-name",
+    "owner": "owner",
+    "status": "status",
+    "start-date": "start-date",
+    "start date": "start-date",
+    "end-date": "end-date",
+    "end date": "end-date",
+}
+
+DATE_PATTERN = r"^\d{4}/\d{1,2}/\d{1,2}$"
+DATE_RE = re.compile(DATE_PATTERN)
+TODO_PATTERN = r"\bTODO\b"
+TODO_RE = re.compile(TODO_PATTERN, re.IGNORECASE)
+TASK_HEADING_PATTERN = r"^###\s+(.*)"
+TASK_HEADING_RE = re.compile(TASK_HEADING_PATTERN)
+META_LINE_PATTERN = r"^[\-\*]\s*([^:]+):\s*(.*)$"
+META_LINE_RE = re.compile(META_LINE_PATTERN)
+
+VAGUE_KEYWORDS = (
+    "investigate",
+    "research",
+    "explore",
+    "analysis",
+    "assess",
+    "assessment",
+    "evaluate",
+    "evaluation",
+    "review",
+    "understand",
+    "ideate",
+    "brainstorm",
+)
+
+TANGIBLE_KEYWORDS = (
+    "pr",
+    "issue",
+    "issues",
+    "pull request",
+    "merge request",
+    "test",
+    "tests",
+    "notion",
+    "doc",
+    "docs",
+    "documentation",
+    "report",
+    "reports",
+    "dashboard",
+    "script",
+    "plan",
+    "plans",
+    "page",
+    "pages",
+    "spec",
+    "specs",
+    "analysis doc",
+    "deliverable",
+    "deliverables",
+)
+
+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

@@ -0,0 +1,101 @@
+"""Commitment identity extraction and related validation."""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+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>.+)$")
+
+
+@dataclass
+class CommitmentIdentity:
+    unit: str
+    quarter: str
+    area: str
+    slug: str
+    expected_tags: List[str]
+    expected_identifier: str
+    expected_base: str
+
+
+def derive_identity(path: Path) -> Optional[CommitmentIdentity]:
+    """Infer roadmap identity metadata from the file path."""
+    try:
+        relative = path.resolve().relative_to(CONTENT_ROOT)
+    except ValueError:
+        return None
+    if len(relative.parts) < 3 or should_skip(path):
+        return None
+
+    unit, area = relative.parts[0], relative.parts[1]
+    match = FILENAME_PATTERN.match(path.stem)
+    if not match:
+        return None
+
+    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(
+        unit=unit,
+        quarter=quarter,
+        area=area,
+        slug=slug,
+        expected_tags=expected_tags,
+        expected_identifier=expected_identifier,
+        expected_base=expected_base,
+    )
+
+
+def validate_identity(
+    path: Path,
+    front_matter: Dict[str, object],
+    lines: List[str],
+    body_start: int,
+    identity: CommitmentIdentity,
+) -> List[str]:
+    """Validate tags and inline identifier for a commitment."""
+    issues: List[str] = []
+
+    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})"
+            )
+    else:
+        issues.append(
+            f"{path}: tags must be a list matching {identity.expected_tags!r}"
+        )
+
+    identifier_value: Optional[str] = None
+    identifier_line: Optional[int] = None
+    for idx in range(body_start, len(lines)):
+        stripped = lines[idx].strip()
+        match = IDENTIFIER_PATTERN.match(stripped)
+        if match:
+            identifier_value = match.group(1)
+            identifier_line = idx + 1
+            break
+
+    if identifier_value is None:
+        issues.append(
+            f"{path}:{body_start + 1}: missing commitment identifier `"
+            f"{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}`)"
+        )
+
+    return issues
+
+
+__all__ = ["CommitmentIdentity", "derive_identity", "validate_identity"]

tools/roadmap_validator/paths.py

@@ -0,0 +1,73 @@
+"""Filesystem helpers for roadmap validation."""
+
+import os
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from .constants import DEFAULT_SKIP_FILENAMES
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CONTENT_ROOT = REPO_ROOT / "content"
+ENV_SKIP_FILENAMES = {
+    entry.strip() for entry in os.environ.get("ROADMAP_VALIDATION_SKIP", "").split() if entry.strip()
+}
+SKIP_FILENAMES = {name.lower() for name in (DEFAULT_SKIP_FILENAMES | ENV_SKIP_FILENAMES)}
+
+
+def should_skip(path: Path) -> bool:
+    """Return True if the file should be ignored by the validator."""
+    return path.name.lower() in SKIP_FILENAMES
+
+
+def resolve_user_path(raw_target: str) -> Optional[Path]:
+    """Resolve a user-supplied path relative to cwd, repo root, or content root."""
+    raw_path = Path(raw_target).expanduser()
+    search_paths: List[Path] = []
+    if raw_path.is_absolute():
+        search_paths.append(raw_path)
+    else:
+        search_paths.extend(
+            [
+                Path.cwd() / raw_path,
+                REPO_ROOT / raw_path,
+                CONTENT_ROOT / raw_path,
+            ]
+        )
+    for candidate in search_paths:
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def resolve_targets(targets: Iterable[str]) -> List[Path]:
+    """Expand iterable of target paths into unique Markdown files."""
+    md_files: List[Path] = []
+    seen: set[Path] = set()
+    for raw_target in targets:
+        target = resolve_user_path(raw_target)
+        if target is None:
+            sys.stderr.write(f"Warning: skipping unknown path {raw_target!r}\n")
+            continue
+        if target.is_dir():
+            for file_path in sorted(target.rglob("*.md")):
+                if should_skip(file_path) or file_path in seen:
+                    continue
+                md_files.append(file_path)
+                seen.add(file_path)
+        elif target.is_file() and target.suffix.lower() == ".md":
+            if should_skip(target) or target in seen:
+                continue
+            md_files.append(target)
+            seen.add(target)
+        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",
+]