@danmoisan/drm-copilot-mcp 0.0.1

package/resources/scripts/dev_tools/pr_context/feature_docs.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .models import FeatureDocExcerpt, section, truncate
+from .verification_evidence import discover_canonical_evidence_files
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+def parse_section(markdown: str, heading: str) -> str:
+    escaped = re.escape(heading)
+    pattern = rf"^##\s+{escaped}\s*\r?\n(.*?)(?=^##\s+|\Z)"
+    match = re.search(pattern, markdown, flags=re.MULTILINE | re.DOTALL)
+    if not match:
+        return ""
+    return match.group(1).strip()
+
+
+def completed_plan_tasks(markdown: str, *, limit: int = 10) -> list[str]:
+    tasks: list[str] = []
+    for line in markdown.splitlines():
+        if re.search(r"\[x\]", line, flags=re.IGNORECASE):
+            cleaned = re.sub(r"^[-*]\s*\[[xX]\]\s*", "", line).strip()
+            tasks.append(cleaned)
+        if len(tasks) >= limit:
+            break
+    return tasks
+
+
+def extract_issue_references(text: str) -> list[str]:
+    if not text:
+        return []
+    matches = re.findall(r"(?<!\w)#\d+|\b[A-Z][A-Z0-9]+-\d+\b", text)
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for item in matches:
+        if item not in seen:
+            seen.add(item)
+            ordered.append(item)
+    return ordered
+
+
+def _resolve_feature_dir(base_dir: Path, feature: str) -> Path | None:
+    direct = base_dir / feature
+    if direct.exists():
+        return direct
+
+    pattern = re.compile(rf"(?:^|[-_]){re.escape(feature)}(?:[-_]|$)")
+    strong_matches: list[Path] = []
+    weak_matches: list[Path] = []
+
+    for candidate in sorted(base_dir.iterdir()):
+        if not candidate.is_dir():
+            continue
+        name = candidate.name
+        if pattern.search(name):
+            strong_matches.append(candidate)
+        elif feature in name:
+            weak_matches.append(candidate)
+
+    if strong_matches:
+        return strong_matches[0]
+    if weak_matches:
+        return weak_matches[0]
+    return None
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def _latest_glob_path(directory: Path, pattern: str) -> Path | None:
+    """Return the lexicographically latest matching file path.
+
+    Purpose:
+        Feature folders commonly use timestamped filenames (for example
+        `plan.<timestamp>.md`). Lexicographic ordering over the timestamp suffix
+        yields deterministic "latest" selection.
+
+    Args:
+        directory (Path): Directory to search.
+        pattern (str): Glob pattern to match.
+
+    Returns:
+        Path | None: Latest matching path, or None if no matches.
+
+    Side Effects:
+        Reads directory entries.
+    """
+    matches = sorted(directory.glob(pattern))
+    return matches[-1] if matches else None
+
+
+def _verification_text(plan_text: str) -> str:
+    for heading in ("Verification", "Test Plan"):
+        section_text = parse_section(plan_text, heading)
+        if section_text:
+            return section_text
+    return ""
+
+
+def _parse_primary_issue_from_metadata(
+    *, spec_text: str, story_text: str, issue_text: str
+) -> str | None:
+    """Parse deterministic primary issue from metadata lines only.
+
+    Args:
+        spec_text: Full `spec.md` text for the feature.
+        story_text: Full `user-story.md` text for the feature.
+        issue_text: Full `issue.md` text for the feature (minor-audit source).
+
+    Returns:
+        A normalized issue reference (for example `#46`) when an explicit
+        metadata line `Issue: #NN` is found; otherwise `None`.
+
+    Side Effects:
+        None.
+    """
+    # Search metadata-style lines only so narrative mentions never become the
+    # deterministic primary issue source.
+    pattern = re.compile(r"^\s*[-*]?\s*Issue:\s*(#\d+)\s*$", re.IGNORECASE)
+
+    # Prefer spec metadata first, then story, then issue.md.
+    for source_text in (spec_text, story_text, issue_text):
+        for line in source_text.splitlines():
+            match = pattern.match(line)
+            if match:
+                return match.group(1)
+    return None
+
+
+def _parse_readiness_value(text: str) -> str | None:
+    """Normalize readiness value from a feature-audit markdown payload.
+
+    Args:
+        text: Raw markdown content from a `feature-audit.*.md` file.
+
+    Returns:
+        One of `PASS`, `NEEDS REVISION`, `BLOCKED`, or `None`.
+
+    Side Effects:
+        None.
+    """
+    # Normalize away Markdown emphasis so template-driven lines like
+    # `**Overall feature readiness:** **PASS**` are parseable using a single
+    # canonical regex.
+    normalized = text.replace("**", "")
+    match = re.search(
+        r"^\s*(?:Readiness|Overall feature readiness):\s*(.+?)\s*$",
+        normalized,
+        flags=re.MULTILINE | re.IGNORECASE,
+    )
+    if not match:
+        return None
+    value = match.group(1).strip().upper()
+    if value in {"PASS", "NEEDS REVISION", "BLOCKED"}:
+        return value
+    return None
+
+
+def _resolve_readiness_signal(feature_dir: Path) -> tuple[str | None, Path | None]:
+    """Resolve readiness signal from the newest readable `feature-audit.*.md`.
+
+    Args:
+        feature_dir: Active feature directory containing audit artifacts.
+
+    Returns:
+        tuple[str | None, Path | None]:
+            - Readiness (`PASS`, `NEEDS REVISION`, `BLOCKED`) or `None`.
+            - The audit file path that produced the readiness value, or `None`.
+
+    Side Effects:
+        Reads local feature audit files from disk.
+    """
+    audit_files = sorted(feature_dir.glob("feature-audit.*.md"))
+    # Evaluate newest-first based on lexicographic timestamp suffix.
+    # Intent: We prefer the newest audit that contains a parseable readiness
+    # marker, which allows older audits to coexist without overriding newer
+    # PASS/REVISION/BLOCKED states.
+    for audit_path in reversed(audit_files):
+        readiness = _parse_readiness_value(_read_text(audit_path))
+        if readiness:
+            return readiness, audit_path
+    return None, None
+
+
+def gather_feature_excerpts(
+    root: Path, changed_files: Iterable[str]
+) -> list[FeatureDocExcerpt]:
+    features: set[str] = set()
+    for raw in changed_files:
+        parts = Path(raw).parts
+        if (
+            len(parts) >= 4
+            and parts[0] == "docs"
+            and parts[1] == "features"
+            and parts[2] == "active"
+        ):
+            features.add(parts[3])
+
+    excerpts: list[FeatureDocExcerpt] = []
+    base_dir = root / "docs" / "features" / "active"
+    promoted_dir = root / "docs" / "features" / "potential" / "promoted"
+    for feature in sorted(features):
+        feature_dir: Path | None = _resolve_feature_dir(base_dir, feature)
+        promoted_feature_dir: Path | None = _resolve_feature_dir(promoted_dir, feature)
+        if feature_dir is None and promoted_feature_dir is None:
+            continue
+
+        active_dir = feature_dir or promoted_feature_dir
+        if active_dir is None:
+            continue
+
+        spec_path = active_dir / "spec.md"
+        issue_path = active_dir / "issue.md"
+
+        # Resolve plan path:
+        # - Prefer `plan.md` for legacy features.
+        # - Fall back to newest `plan.<timestamp>.md` for minor-audit flows.
+        plan_path = active_dir / "plan.md"
+        if not plan_path.exists():
+            latest_plan = _latest_glob_path(active_dir, "plan.*.md")
+            if latest_plan is not None:
+                plan_path = latest_plan
+        user_story_path: Path = active_dir / "user-story.md"
+        promoted_story_path = (
+            promoted_feature_dir / "user-story.md"
+            if promoted_feature_dir is not None
+            else None
+        )
+
+        promoted_story_text = (
+            _read_text(promoted_story_path) if promoted_story_path else ""
+        )
+        if promoted_story_path is not None and not user_story_path.exists():
+            user_story_path = promoted_story_path
+
+        user_story_text = _read_text(user_story_path)
+        if (
+            not user_story_text
+            and promoted_story_text
+            and promoted_story_path is not None
+        ):
+            user_story_text = promoted_story_text
+            user_story_path = promoted_story_path
+
+        spec_text = _read_text(spec_path)
+        issue_text = _read_text(issue_path)
+        plan_text = _read_text(plan_path)
+        primary_issue_ref = _parse_primary_issue_from_metadata(
+            spec_text=spec_text,
+            story_text=user_story_text,
+            issue_text=issue_text,
+        )
+        readiness_signal, readiness_source = _resolve_readiness_signal(active_dir)
+
+        spec_parts: list[str] = []
+        for heading in (
+            "Context",
+            "Root Cause",
+            "Root Cause/Problem",
+            "Problem",
+            "Proposed Fix",
+            "Acceptance Criteria",
+            "Constraints & Risks",
+            "Behavior",
+            "Overview",
+        ):
+            section_text = parse_section(spec_text, heading)
+            if section_text:
+                spec_parts.append(f"{heading}: {truncate(section_text)}")
+
+        plan_tasks = completed_plan_tasks(plan_text)
+        plan_section = (
+            "\n".join(f"- {task}" for task in plan_tasks) if plan_tasks else ""
+        )
+        verification_text = _verification_text(plan_text)
+        verification_block = (
+            "Plan verification notes:\n" + truncate(verification_text)
+            if verification_text
+            else ""
+        )
+
+        story_parts: list[str] = []
+        story_statements = parse_section(user_story_text, "Story Statement")
+        if story_statements:
+            story_lines = [
+                line.strip("- ")
+                for line in story_statements.splitlines()
+                if line.strip()
+            ]
+            if story_lines:
+                story_parts.append(
+                    "Story Statement:\n"
+                    + "\n".join(f"- {line}" for line in story_lines)
+                )
+        problem_section = parse_section(user_story_text, "Problem / Why")
+        if problem_section:
+            story_parts.append("Problem / Why:\n" + truncate(problem_section))
+        if not story_parts and promoted_story_text:
+            promoted_problem = parse_section(promoted_story_text, "Problem / Why")
+            if not promoted_problem:
+                promoted_problem = parse_section(promoted_story_text, "Summary")
+            if promoted_problem:
+                story_parts.append("Problem / Why:\n" + truncate(promoted_problem))
+
+        lines: list[str] = [section(f"Feature doc: {feature}")]
+        if story_parts:
+            lines.append("User story excerpts:\n" + "\n\n".join(story_parts))
+        if spec_parts:
+            lines.append("Spec excerpts:\n" + "\n\n".join(spec_parts))
+        if plan_section:
+            lines.append("Plan completed tasks:\n" + plan_section)
+        if verification_block:
+            lines.append(verification_block)
+        if len(lines) == 1:
+            lines.append("(no spec/plan/user-story excerpts found)")
+
+        context_files = [
+            path.relative_to(root).as_posix()
+            for path in (spec_path, issue_path, plan_path, user_story_path)
+            if path.exists()
+        ]
+        if readiness_source is not None:
+            context_files.append(readiness_source.relative_to(root).as_posix())
+        # Include canonical evidence files so downstream PR authoring can cite
+        # only enumerated sources while preserving deterministic ordering.
+        evidence_context_files = [
+            path.as_posix() for path in discover_canonical_evidence_files(root, feature)
+        ]
+        issue_refs = extract_issue_references(
+            "\n".join([spec_text, issue_text, plan_text, user_story_text])
+        )
+        excerpts.append(
+            FeatureDocExcerpt(
+                feature=feature,
+                excerpt="\n".join(lines),
+                issue_refs=issue_refs,
+                context_files=sorted(set(context_files + evidence_context_files)),
+                primary_issue_ref=primary_issue_ref,
+                readiness_signal=readiness_signal,
+            )
+        )
+
+    return excerpts

package/resources/scripts/dev_tools/pr_context/git.py

@@ -0,0 +1,153 @@
+"""Git helpers for PR context collection."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+from .models import CommandResult
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class CommandRunner(Protocol):
+    """Runs shell commands and returns structured results."""
+
+    def run(
+        self,
+        args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        allow_error: bool = False,
+    ) -> CommandResult: ...
+
+
+class SubprocessRunner(CommandRunner):
+    """Command runner that shells out using subprocess.run."""
+
+    def run(
+        self,
+        args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        allow_error: bool = False,
+    ) -> CommandResult:
+        """
+        Execute a command using subprocess and capture its output.
+
+        Purpose:
+            Run the provided arguments while capturing stdout, stderr, and the exit
+            code for downstream processing.
+
+        Args:
+            args (Sequence[str]): Command and arguments to execute.
+            cwd (Path | None): Optional working directory for the subprocess.
+            allow_error (bool): When False, raise on non-zero exit codes; otherwise
+                return the captured result regardless of status.
+
+        Returns:
+            CommandResult: Captured stdout, stderr, and exit code.
+
+        Raises:
+            RuntimeError: If the subprocess exits non-zero and allow_error is False.
+
+        Side Effects:
+            Spawns a subprocess decoded as UTF-8 with replacement for undecodable
+            bytes to avoid Windows code-page failures.
+        """
+        # We only invoke git with argument lists we construct, not user-supplied
+        # input.
+        completed = subprocess.run(  # noqa: S603
+            args,
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+            shell=False,
+        )
+
+        stdout = (completed.stdout or "").rstrip("\n")
+        stderr = (completed.stderr or "").rstrip("\n")
+        result = CommandResult(
+            stdout=stdout, stderr=stderr, code=int(completed.returncode)
+        )
+
+        if not allow_error and result.code != 0:
+            joined = (stdout + "\n" + stderr).strip()
+            raise RuntimeError(f"{' '.join(args)} failed ({result.code}): {joined}")
+
+        return result
+
+
+class GitClient:
+    """Thin wrapper around git for typed access."""
+
+    def __init__(self, runner: CommandRunner, cwd: Path) -> None:
+        self._runner = runner
+        self._cwd = cwd
+
+    @property
+    def cwd(self) -> Path:
+        """Current working directory for git operations."""
+        return self._cwd
+
+    def run(self, args: Sequence[str], *, allow_error: bool = False) -> CommandResult:
+        return self._runner.run(["git", *args], cwd=self._cwd, allow_error=allow_error)
+
+    def resolve_root(self) -> Path:
+        candidate = self._cwd / ".git"
+        if candidate.exists():
+            return self._cwd
+
+        top = self.run(["rev-parse", "--show-toplevel"]).stdout
+        # Preserve git's reported root without forcing OS-specific drive resolution
+        return Path(top)
+
+    def rev_parse(self, ref: str) -> str:
+        return self.run(["rev-parse", "--verify", ref]).stdout
+
+    def remote_verbose(self) -> str:
+        return self.run(["remote", "-v"]).stdout
+
+    def branch_name(self) -> str:
+        return self.run(["rev-parse", "--abbrev-ref", "HEAD"]).stdout
+
+    def upstream(self) -> str:
+        res = self.run(
+            ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+            allow_error=True,
+        )
+        return res.stdout
+
+    def status_short(self) -> str:
+        return self.run(["status", "-sb"]).stdout
+
+    def untracked(self) -> str:
+        return self.run(["ls-files", "--others", "--exclude-standard"]).stdout
+
+    def diff_name_status(self, *, staged: bool) -> str:
+        args = ["diff", "--name-status"]
+        if staged:
+            args.insert(1, "--cached")
+        return self.run(args, allow_error=True).stdout
+
+    def diff_patch(self, *, staged: bool) -> str:
+        args = ["diff"]
+        if staged:
+            args.append("--cached")
+        return self.run(args, allow_error=True).stdout
+
+    def merge_base(self, base: str, head: str) -> str:
+        return self.run(["merge-base", base, head]).stdout
+
+    def log(self, fmt: str, rev_range: str) -> str:
+        return self.run(
+            ["log", "--date=short", fmt, rev_range], allow_error=True
+        ).stdout
+
+    def diff_range(self, args: Sequence[str]) -> str:
+        return self.run(["diff", *args], allow_error=True).stdout