@danmoisan/drm-copilot-mcp 0.0.1

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

@@ -0,0 +1,256 @@
+"""Feature-document excerpt helpers for PR context rendering."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .models import FeatureDocExcerpt, section, truncate
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+def parse_section(markdown: str, heading: str) -> str:
+    """Extract markdown content under a top-level `##` heading."""
+    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 _extract_issue_references(text: str) -> list[str]:
+    """Extract normalized issue reference tokens from freeform text."""
+    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 completed_plan_tasks(markdown: str, *, limit: int = 10) -> list[str]:
+    """Return up to `limit` completed checklist items from markdown."""
+    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 directory_exists(path: Path) -> bool:
+    """Return whether the provided path exists."""
+    return path.exists()
+
+
+def resolve_feature_dir(base_dir: Path, feature: str) -> Path | None:
+    """Resolve feature directory by exact, strong-pattern, then weak match."""
+    direct = base_dir / feature
+    if directory_exists(direct):
+        return direct
+
+    if not directory_exists(base_dir):
+        return None
+
+    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_file(path: Path) -> str:
+    """Read UTF-8 text if the path exists, otherwise return an empty string."""
+    return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def extract_features_from_paths(changed_files: Iterable[str]) -> set[str]:
+    """Extract feature directory names from `docs/features/active/**` paths."""
+    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])
+    return features
+
+
+def extract_spec_parts(spec_text: str) -> list[str]:
+    """Extract high-value sections from a feature spec document."""
+    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)}")
+    return spec_parts
+
+
+def extract_plan_sections(plan_text: str) -> tuple[str, str]:
+    """Extract completed tasks and verification notes from a plan document."""
+    plan_tasks = completed_plan_tasks(plan_text)
+    plan_section = "\n".join(f"- {task}" for task in plan_tasks) if plan_tasks else ""
+    # Keep fallback order aligned with feature_docs for consistent semantics.
+    test_plan_section = parse_section(plan_text, "Verification")
+    if not test_plan_section:
+        test_plan_section = parse_section(plan_text, "Test Plan")
+    verification_block = (
+        "Plan verification notes:\n" + truncate(test_plan_section)
+        if test_plan_section
+        else ""
+    )
+    return plan_section, verification_block
+
+
+def extract_story_parts(user_story_text: str, promoted_story_text: str) -> list[str]:
+    """Extract story statement/problem snippets from user-story content."""
+    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))
+    return story_parts
+
+
+def build_excerpt_text(
+    feature: str,
+    story_parts: list[str],
+    spec_parts: list[str],
+    plan_section: str,
+    verification_block: str,
+) -> str:
+    """Build a formatted feature excerpt block from collected sections."""
+    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)")
+    return "\n".join(lines)
+
+
+def gather_feature_excerpts(
+    root: Path, changed_files: Iterable[str]
+) -> list[FeatureDocExcerpt]:
+    """Gather feature excerpt payloads for changed active-feature files."""
+    features = extract_features_from_paths(changed_files)
+    excerpts: list[FeatureDocExcerpt] = []
+    base_dir = root / "docs" / "features" / "active"
+    promoted_dir = root / "docs" / "features" / "potential" / "promoted"
+
+    for feature in sorted(features):
+        feature_dir = resolve_feature_dir(base_dir, feature)
+        promoted_feature_dir = 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"
+        plan_path = active_dir / "plan.md"
+        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_file(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_file(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_file(spec_path)
+        plan_text = read_text_file(plan_path)
+
+        spec_parts = extract_spec_parts(spec_text)
+        plan_section, verification_block = extract_plan_sections(plan_text)
+        story_parts = extract_story_parts(user_story_text, promoted_story_text)
+        excerpt_text = build_excerpt_text(
+            feature, story_parts, spec_parts, plan_section, verification_block
+        )
+
+        context_files = [
+            str(path.relative_to(root))
+            for path in (spec_path, plan_path, user_story_path)
+            if path and path.exists()
+        ]
+        issue_refs = _extract_issue_references(
+            "\n".join([spec_text, plan_text, user_story_text])
+        )
+        excerpts.append(
+            FeatureDocExcerpt(
+                feature=feature,
+                excerpt=excerpt_text,
+                issue_refs=issue_refs,
+                context_files=context_files,
+            )
+        )
+
+    return excerpts

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

@@ -0,0 +1,291 @@
+"""PR context rendering utility helpers extracted from render module."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .models import (
+    CONVENTIONAL_TYPES,
+    IssueDetails,
+    PullRequestDetails,
+    format_list,
+    section,
+    truncate,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from .git import GitClient
+
+
+def select_default_base(git: GitClient) -> str | None:
+    """Select the first existing base ref from standard default candidates."""
+    candidates = [
+        "origin/main",
+        "origin/master",
+        "main",
+        "master",
+        "origin/develop",
+        "develop",
+    ]
+    for ref in candidates:
+        result = git.run(["rev-parse", "--verify", "--quiet", ref], allow_error=True)
+        if result.code == 0 and result.stdout.strip():
+            return ref
+    return None
+
+
+def format_diff_path(path_text: str | None) -> str:
+    """Normalize git diff path output, including rename syntax variants."""
+    if path_text is None:
+        return ""
+    if path_text.strip() == "":
+        return path_text
+
+    trimmed = path_text.strip().strip('"')
+    trimmed = re.sub(r"\{[^{}]*\s=>\s([^{}]*)\}", r"\1", trimmed)
+
+    arrow_match = re.match(r"^\s*(.+?)\s=>\s(.+?)\s*$", trimmed)
+    if arrow_match:
+        return arrow_match.group(2)
+    return trimmed
+
+
+def convert_numstat(numstat_text: str) -> tuple[int, int, list[str]]:
+    """Convert git numstat output into totals and raw path list."""
+    adds = 0
+    dels = 0
+    files: list[str] = []
+
+    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]
+        if add_part.isdigit():
+            adds += int(add_part)
+        if del_part.isdigit():
+            dels += int(del_part)
+        files.append(file_part)
+
+    return adds, dels, files
+
+
+def extension_summary(files: Iterable[str]) -> str:
+    """Summarize changed files by extension."""
+    counts: dict[str, int] = {}
+    for raw in files:
+        name = format_diff_path(raw)
+        ext = "(unknown)"
+        try:
+            suffix = Path(name).suffix
+            ext = suffix if suffix else "(noext)"
+        except ValueError:
+            fallback = re.search(r"\.([A-Za-z0-9_]+)$", name)
+            ext = f".{fallback.group(1)}" if fallback else "(unknown)"
+
+        counts[ext] = counts.get(ext, 0) + 1
+
+    lines = [f"{counts[k]:8d}  {k}" for k in sorted(counts)]
+    return "\n".join(lines)
+
+
+def extract_issue_references(text: str) -> list[str]:
+    """Extract issue tokens like #123 and ABC-123 in encounter order."""
+    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 extract_merge_pr_numbers(subjects: Iterable[str]) -> list[str]:
+    """Extract merged PR numbers from commit subject lines."""
+    numbers: set[str] = set()
+    pattern = re.compile(r"Merge pull request #(\d+)", re.IGNORECASE)
+    for subj in subjects:
+        match = pattern.search(subj)
+        if match:
+            numbers.add(f"#{match.group(1)}")
+    return sorted(numbers)
+
+
+def summarize_conventional_commits(subjects: str) -> str:
+    """Count conventional commit types in subject lines."""
+    counts = {key: 0 for key in CONVENTIONAL_TYPES}
+    counts["other"] = 0
+
+    for line in subjects.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        match = re.match(
+            r"(feat|fix|refactor|perf|docs|test|chore|build|ci|style)(\(|!|:)",
+            line,
+        )
+        label = match.group(1) if match else "other"
+        counts[label] += 1
+
+    non_zero = [(k, v) for k, v in counts.items() if v > 0]
+    if not non_zero:
+        return "(no recognizable conventional commit types)"
+    return "\n".join(f"{name:<9} : {value}" for name, value in non_zero)
+
+
+def format_issue_details(issue: IssueDetails) -> str:
+    """Render structured issue details for PR context appendix output."""
+    comments_text = format_list(issue.comments, "(no comments)")
+    lines = [
+        section(f"Issue {issue.number}: {issue.title}"),
+        f"State: {issue.state}",
+        f"Author: {issue.author}",
+        f"Labels: {', '.join(issue.labels) if issue.labels else '(none)'}",
+        f"Assignees: {', '.join(issue.assignees) if issue.assignees else '(none)'}",
+        f"Created: {issue.created_at}",
+        f"Updated: {issue.updated_at}",
+        "",
+        truncate(issue.body, 1200),
+        "",
+        "Comments:",
+        comments_text,
+    ]
+    if issue.user_story_content:
+        lines.extend(
+            [
+                "",
+                f"User story ({issue.user_story_path or 'user-story.md'}):",
+                truncate(issue.user_story_content, 1200),
+            ]
+        )
+    return "\n".join(lines)
+
+
+def format_pr_details(pr: PullRequestDetails) -> str:
+    """Render structured pull request details for PR context appendix output."""
+    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)'}",
+            truncate(pr.body, 1200),
+            "",
+            "Auto-close issues (from this PR):",
+            format_list(pr.closing_issues, "(none)"),
+            "",
+            "Files (first 15):",
+            format_list(pr.files_changed[:15], "(none)"),
+        ]
+    )
+
+
+def build_close_candidates_section(
+    *,
+    verified: list[str],
+    author_asserted: list[str],
+    referenced: list[str],
+    verified_reason: str,
+    author_reason: str,
+) -> str:
+    """Render close-candidate section grouped by verification source."""
+    all_auto_close = set(verified + author_asserted + referenced)
+    author_auto_close = sorted(all_auto_close)
+    referenced_only = sorted(set(referenced) - all_auto_close)
+
+    return "\n".join(
+        [
+            section("Close candidates"),
+            "Auto-close issues (verified from GitHub PR metadata):",
+            format_list(verified, verified_reason),
+            "",
+            "Auto-close issues (author asserted):",
+            format_list(author_auto_close, author_reason),
+            "",
+            "Referenced issues (detected):",
+            format_list(referenced_only, "(none)"),
+        ]
+    )
+
+
+def build_issues_to_autoclose_section(
+    *,
+    verified: list[str],
+    pending_primary: list[str],
+    readiness_signals: list[str],
+) -> str:
+    """Render approved autoclose section from verified and deterministic pending refs.
+
+    Purpose:
+        Build the summary section consumed by PR-generation prompts for allowed
+        autoclose declarations.
+
+    Args:
+        verified: Issues verified from GitHub PR metadata (`closingIssuesReferences`).
+        pending_primary: Deterministic primary issue refs eligible when
+            readiness is PASS.
+        readiness_signals: Normalized readiness states observed in feature docs.
+
+    Returns:
+        A formatted section with header
+        `===== Issues to autoclose (verified or pending) =====` and either a
+        deterministic list or conservative fallback text.
+
+    Side Effects:
+        None.
+    """
+    # Preserve stable, deterministic ordering: verified issues first, then
+    # pending deterministic issues not already verified.
+    ordered: list[str] = []
+    for issue in verified + pending_primary:
+        if issue and issue not in ordered:
+            ordered.append(issue)
+
+    if ordered:
+        body = format_list(ordered, "(none)")
+    else:
+        # Use explicit conservative wording when readiness is missing/non-PASS.
+        if any(signal == "PASS" for signal in readiness_signals):
+            body = (
+                "None (no verified closing issues and no deterministic pending issue)"
+            )
+        else:
+            body = "None (no verified closing issues and readiness not PASS)"
+
+    return "\n".join([section("Issues to autoclose (verified or pending)"), body])
+
+
+def extract_changed_paths(context_text: str) -> list[str]:
+    """Extract changed file paths from the 'Changed files' section text."""
+    paths: list[str] = []
+    capture = False
+    for line in context_text.splitlines():
+        if line.startswith("===== Changed files"):
+            capture = True
+            continue
+        if capture:
+            if line.startswith("====="):
+                break
+            if line.strip() and "\t" in line:
+                path_part = line.split("\t")[-1]
+                paths.append(format_diff_path(path_part.strip()))
+            elif line.strip():
+                paths.append(format_diff_path(line.strip()))
+    return paths