@danmoisan/drm-copilot-mcp 0.0.1

package/resources/scripts/dev_tools/push_down_copilot_customizations_filesystem.py

@@ -0,0 +1,217 @@
+"""Filesystem abstractions for the push-down customization publisher.
+
+Purpose:
+    Isolate the publisher's filesystem contract and real-disk adapter so the
+    orchestration module can stay focused on validation, rewriting, and summary
+    reporting.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class PushDownFileSystem(Protocol):
+    """
+    Define the filesystem operations required by the push-down publisher.
+
+    Purpose:
+        Provide a small, typed seam that keeps the core publisher logic
+        deterministic in tests while still allowing the production CLI to work
+        against the real filesystem.
+
+    Usage:
+        Pass `RealPushDownFileSystem` in production or a deterministic test
+        double in unit tests.
+
+    Flow:
+        The publisher validates the destination, enumerates source files, then
+        reads and writes text through this protocol.
+
+    Invariants / Constraints:
+        - `list_files()` returns files that are beneath the requested root.
+        - `is_dir()` and `is_file()` reflect the current filesystem state.
+        - `read_text()` and `write_text()` operate on UTF-8 repository text.
+
+    Side Effects:
+        Concrete implementations may touch the real filesystem.
+    """
+
+    def list_files(self, root: Path) -> list[Path]: ...
+
+    def is_dir(self, path: Path) -> bool: ...
+
+    def is_file(self, path: Path) -> bool: ...
+
+    def read_text(self, path: Path) -> str: ...
+
+    def write_text(self, path: Path, content: str) -> None: ...
+
+    def ensure_dir(self, path: Path) -> None: ...
+
+
+class RealPushDownFileSystem:
+    """
+    Implement push-down filesystem operations against the real disk.
+
+    Purpose:
+        Provide the production filesystem behavior for source enumeration,
+        destination writes, and summary-artifact emission.
+
+    Usage:
+        Instantiated by `scripts.dev_tools.push_down_copilot_customizations`
+        when callers do not inject a test double.
+
+    Flow:
+        Uses `pathlib.Path` primitives for recursive enumeration and UTF-8 text
+        I/O.
+
+    Invariants / Constraints:
+        The scoped `.github` trees currently contain repository text content, so
+        this adapter reads and writes UTF-8 text.
+
+    Side Effects:
+        Reads from and writes to the real filesystem.
+    """
+
+    def list_files(self, root: Path) -> list[Path]:
+        """
+        Return all files beneath a root path in sorted order.
+
+        Purpose:
+            Preserve deterministic enumeration for summary artifacts and tests.
+
+        Args:
+            root (Path): Root path to enumerate.
+
+        Returns:
+            list[Path]: Sorted file paths beneath `root`.
+
+        Raises:
+            None.
+
+        Side Effects:
+            Reads directory metadata from disk.
+        """
+        if not root.is_dir():
+            return []
+
+        files: list[Path] = []
+        # Collect files in stable order so summary artifacts remain deterministic.
+        for path in root.rglob("*"):
+            if path.is_file():
+                files.append(path)
+        return sorted(files)
+
+    def is_dir(self, path: Path) -> bool:
+        """
+        Return whether the path is an existing directory.
+
+        Purpose:
+            Support destination validation without leaking `pathlib` directly
+            into the orchestration layer.
+
+        Args:
+            path (Path): Path to inspect.
+
+        Returns:
+            bool: True when `path` exists and is a directory.
+
+        Raises:
+            None.
+
+        Side Effects:
+            Reads filesystem metadata.
+        """
+        return path.is_dir()
+
+    def is_file(self, path: Path) -> bool:
+        """
+        Return whether the path is an existing file.
+
+        Purpose:
+            Let the publisher classify writes as created versus overwritten.
+
+        Args:
+            path (Path): Path to inspect.
+
+        Returns:
+            bool: True when `path` exists and is a file.
+
+        Raises:
+            None.
+
+        Side Effects:
+            Reads filesystem metadata.
+        """
+        return path.is_file()
+
+    def read_text(self, path: Path) -> str:
+        """
+        Read UTF-8 text from a file path.
+
+        Purpose:
+            Provide the production text-read primitive used by the publisher.
+
+        Args:
+            path (Path): File path to read.
+
+        Returns:
+            str: File content decoded as UTF-8.
+
+        Raises:
+            OSError: Propagated when the file cannot be read.
+
+        Side Effects:
+            Reads file contents from disk.
+        """
+        return path.read_text(encoding="utf-8")
+
+    def write_text(self, path: Path, content: str) -> None:
+        """
+        Write UTF-8 text to a file path.
+
+        Purpose:
+            Persist copied customization content and summary artifacts.
+
+        Args:
+            path (Path): Destination file path.
+            content (str): UTF-8 text to write.
+
+        Returns:
+            None.
+
+        Raises:
+            OSError: Propagated when the file cannot be written.
+
+        Side Effects:
+            Creates parent directories and writes LF-normalized file content to
+            disk.
+        """
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8", newline="\n")
+
+    def ensure_dir(self, path: Path) -> None:
+        """
+        Ensure a directory exists.
+
+        Purpose:
+            Share one directory-creation primitive between destination writes
+            and artifact output.
+
+        Args:
+            path (Path): Directory path to create.
+
+        Returns:
+            None.
+
+        Raises:
+            OSError: Propagated when the directory cannot be created.
+
+        Side Effects:
+            Creates the directory path on disk when needed.
+        """
+        path.mkdir(parents=True, exist_ok=True)

package/resources/scripts/dev_tools/push_down_copilot_customizations_rewrites.py

@@ -0,0 +1,293 @@
+"""Reference rewrite helpers for the push-down customization publisher.
+
+Purpose:
+    Keep command-reference normalization and rewrite catalog logic separate from
+    the publisher's orchestration flow so each module stays cohesive and easier
+    to test.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+TRAILING_PUNCTUATION = ".,;:!?)"
+SCRIPT_REFERENCE_PATTERN = re.compile(
+    r"(?:(?:poetry\s+run\s+python\s+-m)\s+)?(?:\$\{workspaceFolder\}[\\/])?scripts(?:\.dev_tools\.[A-Za-z0-9_.]+|[\\/](?:dev_tools|dev-tools)[A-Za-z0-9_.\\/-]+)"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RewriteTarget:
+    """
+    Describe how a known script reference maps to a VS Code command.
+
+    Purpose:
+        Keep rewrite metadata explicit so implemented commands and placeholder
+        commands render the same stable textual command-reference format.
+
+    Usage:
+        Selected by normalized script-reference keys during text rewriting.
+
+    Flow:
+        A matched reference normalizes to `normalized_key`, then the target is
+        rendered through `render_command_reference()`.
+
+    Invariants / Constraints:
+        `command_id` values must match the extension's registered command IDs.
+
+    Side Effects:
+        None.
+
+    Attributes:
+        normalized_key (str): Canonical lookup key for a script reference.
+        command_id (str): VS Code command identifier.
+        title (str): User-facing command title.
+        script_reference (str): Original script reference documented by the
+            placeholder contract.
+        is_placeholder (bool): Whether the command intentionally remains a
+            placeholder.
+    """
+
+    normalized_key: str
+    command_id: str
+    title: str
+    script_reference: str
+    is_placeholder: bool
+
+
+def build_rewrite_catalog() -> dict[str, RewriteTarget]:
+    """
+    Build the command rewrite catalog for supported script references.
+
+    Purpose:
+        Keep the supported rewrite surface explicit and deterministic.
+
+    Args:
+        None.
+
+    Returns:
+        dict[str, RewriteTarget]: Catalog keyed by normalized reference.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    targets = (
+        RewriteTarget(
+            normalized_key="scripts.dev_tools.pr_context.collector",
+            command_id="drmCopilotExtension.collectPrContext",
+            title="drm-copilot: Collect PR Context",
+            script_reference="scripts.dev_tools.pr_context.collector",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts.dev_tools.new_active_feature_folder",
+            command_id="drmCopilotExtension.newActiveFeatureFolder",
+            title="drm-copilot: New Active Feature Folder",
+            script_reference="scripts.dev_tools.new_active_feature_folder",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts.dev_tools.potential_to_issue",
+            command_id="drmCopilotExtension.potentialToIssue",
+            title="drm-copilot: Potential To Issue",
+            script_reference="scripts.dev_tools.potential_to_issue",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts/dev_tools/new_potential_bug_entry.py",
+            command_id="drmCopilotExtension.newPotentialBugEntry",
+            title="drm-copilot: New Potential Bug Entry",
+            script_reference="scripts/dev_tools/new_potential_bug_entry.py",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts/dev_tools/new-potential-entry.ps1",
+            command_id="drmCopilotExtension.newPotentialEntry",
+            title="drm-copilot: New Potential Entry",
+            script_reference="scripts/dev-tools/new-potential-entry.ps1",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts.dev_tools.push_down_copilot_customizations",
+            command_id="drmCopilotExtension.pushDownCopilotCustomizations",
+            title="drm-copilot: Push Down Copilot Customizations",
+            script_reference="scripts.dev_tools.push_down_copilot_customizations",
+            is_placeholder=False,
+        ),
+        RewriteTarget(
+            normalized_key="scripts/dev_tools/sync-agents-from-instructions.ps1",
+            command_id="drmCopilotExtension.syncAgentsFromInstructions",
+            title="drm-copilot: Sync AGENTS.md from Instructions",
+            script_reference="scripts/dev-tools/sync-agents-from-instructions.ps1",
+            is_placeholder=False,
+        ),
+    )
+    return {target.normalized_key: target for target in targets}
+
+
+def render_command_reference(target: RewriteTarget) -> str:
+    """
+    Render a canonical textual command reference for copied files.
+
+    Purpose:
+        Keep replacement text uniform regardless of whether the destination
+        command is implemented or still a placeholder.
+
+    Args:
+        target (RewriteTarget): Catalog entry for the matched reference.
+
+    Returns:
+        str: Stable textual command reference.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    return f"VS Code command: `{target.title}` (command ID: `{target.command_id}`)"
+
+
+def normalize_reference_for_lookup(reference_text: str) -> str:
+    """
+    Normalize a matched textual reference before catalog lookup.
+
+    Purpose:
+        Collapse workspace prefixes and slash variants onto canonical lookup
+        keys so the rewrite catalog has one stable matching surface.
+
+    Args:
+        reference_text (str): Raw matched script reference.
+
+    Returns:
+        str: Canonical lookup key.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    normalized = reference_text.strip()
+    normalized = re.sub(r"^poetry\s+run\s+python\s+-m\s+", "", normalized)
+    normalized = normalized.replace("${workspaceFolder}\\", "")
+    normalized = normalized.replace("${workspaceFolder}/", "")
+    normalized = normalized.replace("\\", "/")
+    normalized = normalized.replace("scripts/dev-tools/", "scripts/dev_tools/")
+    return normalized
+
+
+def split_trailing_punctuation(reference_text: str) -> tuple[str, str]:
+    """
+    Split a matched reference into its core text and trailing punctuation.
+
+    Purpose:
+        Preserve prose punctuation so rewrites do not disturb surrounding
+        documentation.
+
+    Args:
+        reference_text (str): Matched reference including surrounding
+            punctuation.
+
+    Returns:
+        tuple[str, str]: Core reference text and trailing punctuation.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    core = reference_text
+    suffix = ""
+    # Preserve trailing sentence punctuation so rewrites do not disturb prose.
+    while core and core[-1] in TRAILING_PUNCTUATION:
+        suffix = core[-1] + suffix
+        core = core[:-1]
+    return core, suffix
+
+
+def rewrite_matched_reference(
+    reference_text: str,
+    catalog: dict[str, RewriteTarget],
+) -> tuple[str, int, int, list[str]]:
+    """
+    Rewrite one matched script reference when it belongs to the catalog.
+
+    Purpose:
+        Handle one matched reference so the surrounding regex pass can stay
+        focused on streaming replacements and counts.
+
+    Args:
+        reference_text (str): Matched script reference text.
+        catalog (dict[str, RewriteTarget]): Lookup table keyed by normalized
+            reference.
+
+    Returns:
+        tuple[str, int, int, list[str]]: Replacement text, implemented rewrite
+        count, placeholder rewrite count, and unmatched references.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    core_reference, suffix = split_trailing_punctuation(reference_text)
+    normalized_reference = normalize_reference_for_lookup(core_reference)
+    target = catalog.get(normalized_reference)
+    if target is None:
+        return reference_text, 0, 0, [normalized_reference]
+
+    replacement = render_command_reference(target) + suffix
+    if target.is_placeholder:
+        return replacement, 0, 1, []
+    return replacement, 1, 0, []
+
+
+def rewrite_text_references(text: str) -> tuple[str, int, int, list[str]]:
+    """
+    Rewrite supported script references within text content.
+
+    Purpose:
+        Apply replacements only to matched script references and report unknown
+        references without changing them.
+
+    Args:
+        text (str): Source text to rewrite.
+
+    Returns:
+        tuple[str, int, int, list[str]]: Rewritten text, implemented rewrite
+        count, placeholder rewrite count, and ordered unmatched references.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    catalog = build_rewrite_catalog()
+    rewritten_count = 0
+    placeholder_count = 0
+    unmatched_references: list[str] = []
+
+    def replace_match(match: re.Match[str]) -> str:
+        """Rewrite one regex match while accumulating deterministic counters."""
+        nonlocal rewritten_count, placeholder_count
+        replacement, rewritten_delta, placeholder_delta, unmatched = (
+            rewrite_matched_reference(match.group(0), catalog)
+        )
+        rewritten_count += rewritten_delta
+        placeholder_count += placeholder_delta
+        # Preserve first-seen order so unmatched reporting stays deterministic.
+        for reference in unmatched:
+            if reference not in unmatched_references:
+                unmatched_references.append(reference)
+        return replacement
+
+    rewritten_text = SCRIPT_REFERENCE_PATTERN.sub(replace_match, text)
+    return rewritten_text, rewritten_count, placeholder_count, unmatched_references