@danmoisan/drm-copilot-mcp 0.0.1

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

@@ -0,0 +1,386 @@
+"""Helper routines for PR context rendering and summarization."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from .models import (
+    IssueDetails,
+    PullRequestDetails,
+    format_list,
+    section,
+    truncate_lines,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .git import GitClient
+
+__all__ = [
+    "append_generation_timestamp",
+    "bucket_text",
+    "extract_digest_bullets",
+    "is_scoping_doc",
+    "issue_appendix",
+    "issue_digest",
+    "last_with_truncation",
+    "parse_name_status_map",
+    "parse_numstat_detailed",
+    "parse_section",
+    "pr_appendix",
+    "pr_digest",
+    "scoping_doc_changes",
+]
+
+
+def last_with_truncation(items: list[str], limit: int) -> tuple[list[str], bool]:
+    if len(items) <= limit:
+        return items, False
+    return items[-limit:], True
+
+
+def extract_digest_bullets(body: str, *, headings: list[str], limit: int) -> list[str]:
+    bullets: list[str] = []
+    for heading in headings:
+        section_text = parse_section(body, heading)
+        if not section_text:
+            continue
+        for line in section_text.splitlines():
+            if not line.strip():
+                continue
+            cleaned = line.lstrip("-*").strip()
+            bullets.append(f"{heading}: {cleaned}")
+            if len(bullets) >= limit:
+                return bullets
+    return bullets[:limit]
+
+
+def issue_digest(issue: IssueDetails) -> str:
+    bullets = extract_digest_bullets(
+        issue.body,
+        headings=[
+            "Why",
+            "Context",
+            "Root Cause",
+            "Constraints",
+            "Acceptance Criteria",
+            "Test Strategy",
+            "Risks",
+            "Verification",
+            "Follow-ups",
+        ],
+        limit=8,
+    )
+    if not bullets:
+        bullets.append(f"State: {issue.state}")
+        if issue.labels:
+            bullets.append(f"Labels: {', '.join(issue.labels)}")
+
+    selected_comments, truncated = last_with_truncation(issue.comments, 3)
+    comment_block = (
+        "\n".join(f"- {comment}" for comment in selected_comments)
+        if selected_comments
+        else "(no comments)"
+    )
+    if truncated:
+        comment_block += "\nTRUNCATED: last 3 comments shown"
+
+    metadata = [
+        f"Identifier: {issue.number}",
+        f"Title: {issue.title}",
+        f"Author: {issue.author}",
+        f"Assignees: {', '.join(issue.assignees) if issue.assignees else '(none)'}",
+        f"Labels: {', '.join(issue.labels) if issue.labels else '(none)'}",
+        f"State: {issue.state}",
+        f"Last updated: {issue.updated_at}",
+    ]
+    return "\n".join(
+        [
+            "\n".join(metadata),
+            "Key bullets:",
+            "\n".join(f"- {entry}" for entry in bullets),
+            "",
+            "Recent comments:",
+            comment_block,
+        ]
+    )
+
+
+def pr_digest(pr: PullRequestDetails) -> str:
+    bullets = extract_digest_bullets(
+        pr.body,
+        headings=[
+            "Why",
+            "Context",
+            "Root Cause",
+            "Constraints",
+            "Acceptance Criteria",
+            "Test Strategy",
+            "Risks",
+            "Verification",
+            "Follow-ups",
+        ],
+        limit=8,
+    )
+    if not bullets:
+        if pr.files_changed:
+            bullets.append(
+                f"Touches files: {', '.join(pr.files_changed[:3])}"
+                + (" ..." if len(pr.files_changed) > 3 else "")
+            )
+        bullets.append(f"State: {pr.state}")
+
+    metadata = [
+        f"Identifier: {pr.number}",
+        f"Title: {pr.title}",
+        f"Author: {pr.author}",
+        f"Base/Head: {pr.base_ref} <- {pr.head_ref}",
+        f"Last updated: {pr.updated_at}",
+    ]
+    return "\n".join(
+        [
+            "\n".join(metadata),
+            "Key bullets:",
+            "\n".join(f"- {entry}" for entry in bullets),
+        ]
+    )
+
+
+def issue_appendix(issue: IssueDetails) -> str:
+    body_text = truncate_lines(issue.body, 120)
+    comments, truncated = last_with_truncation(issue.comments, 10)
+    comment_text = (
+        "\n".join(f"- {c}" for c in comments) if comments else "(no comments)"
+    )
+    if truncated:
+        comment_text += "\nTRUNCATED: last 10 comments shown"
+    user_story_block = ""
+    if issue.user_story_content:
+        user_story_block = "\n".join(
+            [
+                "",
+                f"User story ({issue.user_story_path or 'user-story.md'}):",
+                truncate_lines(issue.user_story_content, 120),
+            ]
+        )
+    return "\n".join(
+        [
+            section(f"Issue {issue.number}: {issue.title}"),
+            f"State: {issue.state}",
+            f"Labels: {', '.join(issue.labels) if issue.labels else '(none)'}",
+            f"Assignees: {', '.join(issue.assignees) if issue.assignees else '(none)'}",
+            f"Author: {issue.author}",
+            f"Created: {issue.created_at}",
+            f"Updated: {issue.updated_at}",
+            "",
+            body_text,
+            "",
+            "Comments:",
+            comment_text,
+            user_story_block,
+        ]
+    )
+
+
+def pr_appendix(pr: PullRequestDetails) -> str:
+    body_text = truncate_lines(pr.body, 120)
+    return "\n".join(
+        [
+            section(f"Pull Request {pr.number}: {pr.title}"),
+            f"State: {pr.state}",
+            f"Author: {pr.author}",
+            f"Base: {pr.base_ref}",
+            f"Head: {pr.head_ref}",
+            f"Created: {pr.created_at}",
+            f"Updated: {pr.updated_at}",
+            f"Merged: {pr.merged_at or '(not merged)'}",
+            f"Labels: {', '.join(pr.labels) if pr.labels else '(none)'}",
+            f"Assignees: {', '.join(pr.assignees) if pr.assignees else '(none)'}",
+            "",
+            body_text,
+            "",
+            "Auto-close issues (from this PR):",
+            format_list(pr.closing_issues, "(none)"),
+            "",
+            "Files (first 25):",
+            format_list(pr.files_changed[:25], "(none)"),
+        ]
+    )
+
+
+def parse_numstat_detailed(
+    numstat_text: str,
+) -> tuple[int, int, dict[str, tuple[int, int]]]:
+    adds_total = 0
+    dels_total = 0
+    per_file: dict[str, tuple[int, int]] = {}
+    for raw_line in numstat_text.splitlines():
+        if not raw_line.strip():
+            continue
+        parts = raw_line.split("\t")
+        if len(parts) < 3:
+            continue
+        add_part, del_part, file_part = parts[0], parts[1], parts[2]
+        add_count = int(add_part) if add_part.isdigit() else 0
+        del_count = int(del_part) if del_part.isdigit() else 0
+        adds_total += add_count
+        dels_total += del_count
+        per_file[format_diff_path(file_part)] = (add_count, del_count)
+    return adds_total, dels_total, per_file
+
+
+def parse_name_status_map(name_status_text: str) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for raw_line in name_status_text.splitlines():
+        if not raw_line.strip():
+            continue
+        parts = raw_line.split("\t")
+        if len(parts) < 2:
+            continue
+        status = parts[0].strip()
+        path = format_diff_path(parts[-1].strip())
+        mapping[path] = status
+    return mapping
+
+
+def is_scoping_doc(path: str) -> bool:
+    lowered = path.lower()
+    return bool(
+        lowered.startswith("docs/features/")
+        and (
+            lowered.endswith("/spec.md")
+            or lowered.endswith("/plan.md")
+            or lowered.endswith("/bug-remediation-plan.md")
+            or lowered.endswith("/user-story.md")
+            or lowered.endswith("/readme.md")
+        )
+    )
+
+
+def scoping_doc_changes(
+    *,
+    git: GitClient,
+    merge_base: str | None,
+    head_sha: str | None,
+    root: Path,
+    name_status_text: str,
+    numstat_details: dict[str, tuple[int, int]],
+) -> list[tuple[str, bool, list[str], str | None]]:
+    if not merge_base or not head_sha:
+        return []
+    changes: list[tuple[str, bool, list[str], str | None]] = []
+    name_status_map = parse_name_status_map(name_status_text)
+    for path, status in name_status_map.items():
+        if not is_scoping_doc(path):
+            continue
+        additions, deletions = numstat_details.get(path, (0, 0))
+        reasons: list[str] = []
+        material = False
+        if status.startswith("A"):
+            material = True
+            reasons.append("new scoping doc")
+        if additions + deletions >= 15:
+            material = True
+            reasons.append(">=15 lines changed")
+
+        diff_text = git.diff_range(["--unified=0", merge_base, head_sha, "--", path])
+        heading_touched = False
+        for line in diff_text.splitlines():
+            if not line.startswith("+") or line.startswith("+++"):
+                continue
+            stripped = line.lstrip("+").strip()
+            if any(
+                stripped.lower().startswith(prefix.lower())
+                for prefix in (
+                    "## Context",
+                    "## Root Cause",
+                    "## Proposed Fix",
+                    "## Acceptance Criteria",
+                    "## Test Strategy",
+                    "## Risks",
+                )
+            ):
+                heading_touched = True
+                break
+        if heading_touched:
+            material = True
+            reasons.append("key section touched")
+
+        added_lines = [
+            line.lstrip("+").strip()
+            for line in diff_text.splitlines()
+            if line.startswith("+") and not line.startswith("+++")
+        ]
+        if added_lines and all(
+            (not line or line.startswith("[") or line.startswith("http"))
+            for line in added_lines
+        ):
+            reasons.append("link/whitespace-only changes")
+            if (
+                not heading_touched
+                and additions + deletions < 15
+                and not status.startswith("A")
+            ):
+                material = False
+
+        excerpt = None
+        doc_path = root / path
+        if material and doc_path.exists():
+            content = doc_path.read_text(encoding="utf-8")
+            excerpt_parts: list[str] = []
+            for heading in (
+                "Acceptance Criteria",
+                "Root Cause",
+                "Proposed Fix",
+                "Test Strategy",
+            ):
+                section_text = parse_section(content, heading)
+                if section_text:
+                    excerpt_parts.append(
+                        f"{heading}:\n{truncate_lines(section_text, 40)}"
+                    )
+            excerpt = "\n\n".join(excerpt_parts[:3]) if excerpt_parts else None
+
+        changes.append((path, material, reasons, excerpt))
+    return changes
+
+
+def bucket_text(name: str, entries: list[tuple[str, tuple[int, int]]]) -> str:
+    if not entries:
+        return f"{name}: 0 files"
+    sorted_entries = sorted(
+        entries, key=lambda item: item[1][0] + item[1][1], reverse=True
+    )
+    lines = [
+        f"{name}: {len(entries)} files",
+        *(f"- {path} (+{adds}/-{dels})" for path, (adds, dels) in sorted_entries[:10]),
+    ]
+    return "\n".join(lines)
+
+
+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 format_diff_path(path_text: str | None) -> str:
+    from .render import format_diff_path as _fmt
+
+    return _fmt(path_text) if path_text is not None else ""
+
+
+def append_generation_timestamp() -> str:
+    """Generate a timestamp section showing when context was collected.
+
+    Returns:
+        Formatted timestamp section with UTC time
+    """
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S %Z")
+    return section("Context generated") + "\n" + timestamp + "\n"

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

@@ -0,0 +1,171 @@
+"""Discover and parse canonical feature verification evidence artifacts.
+
+Purpose:
+    Provide deterministic discovery and strict schema parsing for canonical
+    evidence markdown files so PR context generation can make traceable
+    verification claims.
+
+Flow:
+    1. Discover canonical evidence files under active feature folders.
+    2. Parse required schema fields from each markdown file.
+    3. Normalize pass/fail/unparseable status from EXIT_CODE.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+REQUIRED_FIELDS: tuple[str, str, str] = ("Timestamp", "Command", "EXIT_CODE")
+CANONICAL_GLOBS: tuple[str, str, str] = (
+    "evidence/qa-gates/**/*.md",
+    "evidence/regression-testing/**/*.md",
+    "evidence/other/**/*.md",
+)
+
+NormalizedResult = Literal["pass", "fail", "unparseable"]
+
+
+@dataclass(frozen=True)
+class VerificationEvidenceRecord:
+    """Represent one parsed canonical evidence artifact.
+
+    Purpose:
+        Carry all fields needed to render verification rows and preserve source
+        traceability to a specific feature evidence file.
+
+    Attributes:
+        feature: Active feature folder identifier.
+        source_file: Repository-relative evidence file path.
+        timestamp: Parsed `Timestamp` field when present.
+        command: Parsed `Command` field when present.
+        exit_code: Parsed `EXIT_CODE` integer when parseable.
+        normalized_result: Deterministic status (`pass`, `fail`, `unparseable`).
+    """
+
+    feature: str
+    source_file: str
+    timestamp: str | None
+    command: str | None
+    exit_code: int | None
+    normalized_result: NormalizedResult
+
+
+def discover_canonical_evidence_files(root: Path, feature: str) -> list[Path]:
+    """Discover canonical evidence files for one active feature.
+
+    Args:
+        root: Repository root path.
+        feature: Active feature directory name under `docs/features/active`.
+
+    Returns:
+        Sorted, deduplicated repository-relative paths for canonical evidence files.
+
+    Side Effects:
+        Reads filesystem metadata through globbing.
+    """
+    feature_root = root / "docs" / "features" / "active" / feature
+    if not feature_root.exists() or not feature_root.is_dir():
+        return []
+
+    discovered: set[Path] = set()
+    # Search canonical evidence roots in a fixed order, then sort for stability.
+    for pattern in CANONICAL_GLOBS:
+        for candidate in feature_root.glob(pattern):
+            if candidate.is_file():
+                discovered.add(candidate.relative_to(root))
+    return sorted(discovered)
+
+
+def parse_verification_evidence_markdown(
+    *, feature: str, source_file: str, markdown: str
+) -> VerificationEvidenceRecord:
+    """Parse required schema fields and normalize verification status.
+
+    Args:
+        feature: Active feature identifier owning the evidence file.
+        source_file: Repository-relative evidence file path.
+        markdown: Raw markdown content to parse.
+
+    Returns:
+        A normalized evidence record with `pass`, `fail`, or `unparseable` result.
+
+    Side Effects:
+        None.
+    """
+    parsed: dict[str, str] = {}
+
+    # Parse `Key: value` rows once and keep only required schema fields.
+    for raw_line in markdown.splitlines():
+        if ":" not in raw_line:
+            continue
+        key, value = raw_line.split(":", 1)
+        key = key.strip()
+        if key in REQUIRED_FIELDS:
+            parsed[key] = value.strip()
+
+    timestamp = parsed.get("Timestamp")
+    command = parsed.get("Command")
+    exit_code_raw = parsed.get("EXIT_CODE")
+
+    if not timestamp or not command or exit_code_raw is None:
+        return VerificationEvidenceRecord(
+            feature=feature,
+            source_file=source_file,
+            timestamp=timestamp,
+            command=command,
+            exit_code=None,
+            normalized_result="unparseable",
+        )
+
+    try:
+        exit_code = int(exit_code_raw)
+    except ValueError:
+        return VerificationEvidenceRecord(
+            feature=feature,
+            source_file=source_file,
+            timestamp=timestamp,
+            command=command,
+            exit_code=None,
+            normalized_result="unparseable",
+        )
+
+    normalized_result: NormalizedResult = "pass" if exit_code == 0 else "fail"
+    return VerificationEvidenceRecord(
+        feature=feature,
+        source_file=source_file,
+        timestamp=timestamp,
+        command=command,
+        exit_code=exit_code,
+        normalized_result=normalized_result,
+    )
+
+
+def parse_verification_evidence_file(
+    *, root: Path, feature: str, relative_path: Path
+) -> VerificationEvidenceRecord:
+    """Read and parse one canonical evidence file.
+
+    Args:
+        root: Repository root path.
+        feature: Active feature identifier.
+        relative_path: Repository-relative evidence file path.
+
+    Returns:
+        Parsed normalized evidence record.
+
+    Raises:
+        OSError: Propagated when the evidence file cannot be read.
+
+    Side Effects:
+        Reads evidence file content from disk.
+    """
+    markdown = (root / relative_path).read_text(encoding="utf-8")
+    return parse_verification_evidence_markdown(
+        feature=feature,
+        source_file=relative_path.as_posix(),
+        markdown=markdown,
+    )

package/resources/scripts/dev_tools/prompt_mode_contract.py

@@ -0,0 +1,152 @@
+"""Shared issue.md work-mode contract helpers for prompt resolvers.
+
+Purpose:
+    Centralize parsing and fail-closed work-mode resolution so all prompt
+    resolvers use one deterministic contract:
+    1) Parse persisted issue marker when valid.
+    2) Normalize legacy `full` markers to a canonical full-mode variant.
+    3) Fall back to `full-feature` when marker is missing or malformed.
+    4) Surface an auditable fallback or normalization reason string.
+"""
+
+from __future__ import annotations
+
+import re
+
+CANONICAL_WORK_MODES = ("minor-audit", "full-feature", "full-bug")
+LEGACY_FULL_MODE = "full"
+ACCEPTED_WORK_MODES = (*CANONICAL_WORK_MODES, LEGACY_FULL_MODE)
+
+
+def normalize_requested_work_mode(requested_mode: str, promotion_type: str) -> str:
+    """Normalize a requested work mode into a canonical persisted value.
+
+    Purpose:
+        Convert user-facing or legacy CLI values into canonical persisted
+        markers. Plain `full` remains accepted for backward compatibility but is
+        normalized to the deterministic variant that matches the promotion
+        target.
+
+    Args:
+        requested_mode (str): Requested work mode from CLI or caller.
+        promotion_type (str): Promotion or feature type (`feature`, `bug`, etc.).
+
+    Returns:
+        str: Canonical work mode (`minor-audit`, `full-feature`, or `full-bug`).
+
+    Raises:
+        ValueError: If the request is invalid or incompatible with the type.
+    """
+    if requested_mode not in ACCEPTED_WORK_MODES:
+        raise ValueError(
+            "work_mode must be one of: minor-audit, full-feature, full-bug, full"
+        )
+
+    if requested_mode == "minor-audit":
+        return requested_mode
+
+    is_bug = promotion_type == "bug"
+    if requested_mode == LEGACY_FULL_MODE:
+        return "full-bug" if is_bug else "full-feature"
+
+    if requested_mode == "full-bug" and not is_bug:
+        raise ValueError("full-bug may only be used with bug work")
+
+    if requested_mode == "full-feature" and is_bug:
+        raise ValueError("full-feature may not be used with bug work")
+
+    return requested_mode
+
+
+def parse_issue_work_mode(issue_content: str) -> tuple[str | None, bool]:
+    """Parse the work-mode marker from issue.md content.
+
+    Purpose:
+        Extract a valid `- Work Mode:` marker value from issue content while
+        distinguishing malformed marker lines from truly missing markers.
+
+    Args:
+        issue_content (str): Raw `issue.md` file content.
+
+    Returns:
+        tuple[str | None, bool]:
+            - Parsed mode (`minor-audit`, `full-feature`, `full-bug`, or legacy
+              `full`) when valid; otherwise None.
+            - Boolean indicating whether a malformed marker line was detected.
+
+    Side Effects:
+        None.
+    """
+    valid_match = re.search(
+        r"(?im)^-\s*Work Mode:\s*(minor-audit|full-feature|full-bug|full)\s*$",
+        issue_content,
+    )
+    if valid_match is not None:
+        return valid_match.group(1), False
+
+    malformed_match = re.search(r"(?im)^-\s*Work Mode:\s*(.+)\s*$", issue_content)
+    return None, malformed_match is not None
+
+
+def resolve_selected_work_mode(issue_content: str | None) -> str:
+    """Resolve selected work mode with fail-closed behavior.
+
+    Purpose:
+        Provide a deterministic selected mode for templates by honoring a valid
+        marker when present, normalize legacy `full` to `full-feature`, and fail
+        closed to `full-feature` for all other states.
+
+    Args:
+        issue_content (str | None): Raw issue content, or None when the file is
+            unavailable.
+
+    Returns:
+        str: `minor-audit`, `full-feature`, or `full-bug`.
+
+    Side Effects:
+        None.
+    """
+    if issue_content is None:
+        return "full-feature"
+
+    parsed_mode, _has_malformed_marker = parse_issue_work_mode(issue_content)
+    if parsed_mode is not None:
+        if parsed_mode == LEGACY_FULL_MODE:
+            return "full-feature"
+        return parsed_mode
+
+    return "full-feature"
+
+
+def build_fallback_reason(issue_content: str | None) -> str:
+    """Build a deterministic fallback reason for mode resolution.
+
+    Purpose:
+        Produce a stable reason string suitable for prompt substitution and
+        audit evidence, aligned with fail-closed mode semantics.
+
+    Args:
+        issue_content (str | None): Raw issue content, or None when missing or
+            unreadable.
+
+    Returns:
+        str: `none` when no fallback was needed, otherwise an explicit reason.
+
+    Side Effects:
+        None.
+    """
+    if issue_content is None:
+        return "issue.md missing; fail closed to full-feature"
+
+    parsed_mode, has_malformed_marker = parse_issue_work_mode(issue_content)
+    if parsed_mode is not None:
+        if parsed_mode == LEGACY_FULL_MODE:
+            return (
+                "issue.md Work Mode marker uses legacy full; normalized to full-feature"
+            )
+        return "none"
+
+    if has_malformed_marker:
+        return "issue.md Work Mode marker malformed; fail closed to full-feature"
+
+    return "issue.md Work Mode marker missing; fail closed to full-feature"