boomtick-cli 0.2.1__py3-none-any.whl

dev_tools/utils/git.py

@@ -0,0 +1,68 @@
+"""Git utilities for secure branch operations."""
+import os
+import re
+import subprocess
+from typing import Optional
+from dev_tools.utils import CLIError, log_warn, mask_sensitive_data
+
+class GitUtility:  # pylint: disable=too-few-public-methods
+    """Utility class for Git operations."""
+
+    def __init__(self, token: Optional[str] = None, repo: Optional[str] = None):
+        self.token = token
+        self.repo = repo
+
+    def branch_exists_locally(self, branch: str) -> bool:
+        """Checks if a branch exists in the local repository."""
+        proc = subprocess.run(
+            ["git", "show-ref", "--verify", f"refs/heads/{branch}"],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        return proc.returncode == 0
+
+    def push_branch(self, branch: str) -> bool:
+        """Securely pushes a local branch to the remote origin."""
+        # Security: Validate branch name to prevent injection
+        if not re.match(r"^[a-zA-Z0-9._/-]+$", branch):
+            raise CLIError(f"Invalid branch name: {branch}", code=400)
+
+        try:
+            # Check if branch exists locally
+            if not self.branch_exists_locally(branch):
+                log_warn(f"Local branch '{branch}' not found. Cannot push.")
+                return False
+
+            log_warn(f"Pushing local branch '{branch}' to origin...")
+
+            # Security: Use environment variable for token to avoid leaking in process list
+            env = os.environ.copy()
+            if self.token and self.repo:
+                env["GIT_TOKEN_FOR_PUSH"] = self.token
+                # Use a credential helper to pass the token securely
+                cred_helper = "!f() { echo \"username=x-access-token\"; echo \"password=$GIT_TOKEN_FOR_PUSH\"; }; f"
+                push_url = f"https://github.com/{self.repo}.git"
+                push_args = ["git", "-c", f"credential.helper={cred_helper}", "push", "-u", push_url, branch]
+            else:
+                push_args = ["git", "push", "-u", "origin", branch]
+
+            # Capture output and handle error manually to avoid leaking sensitive info in exceptions
+            push_res = subprocess.run(
+                push_args,
+                capture_output=True,
+                text=True,
+                env=env,
+                check=False
+            )
+
+            if push_res.returncode != 0:
+                sanitized_stderr = mask_sensitive_data(push_res.stderr)
+                log_warn(f"Failed to push branch '{branch}': {sanitized_stderr}")
+                return False
+
+            return True
+
+        except (subprocess.SubprocessError, OSError) as e:
+            log_warn(f"Unexpected error during git push for branch '{branch}': {mask_sensitive_data(str(e))}")
+            return False

dev_tools/ux_report.py

@@ -0,0 +1,213 @@
+# pylint: disable=expression-not-assigned,line-too-long,missing-docstring,too-many-branches,too-many-locals,too-many-statements
+import glob
+import json
+import os
+from datetime import datetime
+
+from dev_tools.utils import log_info
+
+
+def generate_report():
+    artifacts_dir = os.path.join(os.getcwd(), "artifacts", "ux-audit")
+    results_dir = os.path.join(artifacts_dir, "results")
+    lighthouse_dir = os.path.join(artifacts_dir, "lighthouse")
+    issues_dir = os.path.join(artifacts_dir, "issues")
+
+    os.makedirs(issues_dir, exist_ok=True)
+
+    report_lines = [
+        "# UX Audit Report",
+        f"Generated on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n",
+        "## Summary",
+    ]
+
+    findings = []
+
+    result_files = glob.glob(os.path.join(results_dir, "*.json"))
+    report_lines.append(f"- Routes Audited: {len(result_files)}")
+
+    # Aggregate results
+    all_results = []
+    for rf in result_files:
+        with open(rf, "r", encoding="utf-8") as f:
+            all_results.append(json.load(f))
+
+    # Lighthouse summary
+    lh_files = glob.glob(os.path.join(lighthouse_dir, "*.report.json"))
+    if lh_files:
+        report_lines.append("\n## Lighthouse Scores")
+        report_lines.append("| Route | Performance | Accessibility | Best Practices | SEO |")
+        report_lines.append("|-------|-------------|---------------|----------------|-----|")
+        for lhf in lh_files:
+            with open(lhf, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                cats = data.get("categories", {})
+                name = os.path.basename(lhf).replace(".report.json", "")
+                perf = int(cats.get("performance", {}).get("score", 0) * 100)
+                a11y = int(cats.get("accessibility", {}).get("score", 0) * 100)
+                bp = int(cats.get("best-practices", {}).get("score", 0) * 100)
+                seo = int(cats.get("seo", {}).get("score", 0) * 100)
+                report_lines.append(f"| {name} | {perf} | {a11y} | {bp} | {seo} |")
+
+    # High Severity Findings
+    report_lines.append("\n## Key Findings")
+
+    for res in all_results:
+        route = res["route"]
+        vp = res["viewport"]
+        screenshot = res.get("screenshot", "N/A")
+        "mobile" in vp.lower()
+
+        # 1. Accessibility (Axe)
+        if res.get("accessibility") and res["accessibility"].get("violations"):
+            violations = res["accessibility"]["violations"]
+            for v in violations:
+                finding = {
+                    "title": f"Accessibility Violation: {v['id']} on `{route}` ({vp})",
+                    "route": route,
+                    "viewport": vp,
+                    "category": "Accessibility",
+                    "severity": "High" if v["impact"] in ["critical", "serious"] else "Medium",
+                    "evidence": f"Axe violation: {v['description']}. Found on {len(v['nodes'])} elements.",
+                    "recommendation": f"Fix {v['id']} issues. Help: {v['helpUrl']}",
+                    "screenshot": screenshot,
+                    "user_impact": "Users with disabilities may be unable to navigate or interact with the page effectively.",
+                    "acceptance_criteria": [
+                        "Lighthouse/Axe accessibility audit passes for this category",
+                        "Element is keyboard accessible",
+                        "Screen reader announcements are clear",
+                    ],
+                }
+                findings.append(finding)
+
+        # 2. Layout Overflow
+        if res.get("overflow"):
+            finding = {
+                "title": f"Horizontal Overflow on `{route}` ({vp})",
+                "route": route,
+                "viewport": vp,
+                "category": "Layout",
+                "severity": "High",
+                "evidence": f"Detected {len(res['overflow'])} elements overflowing viewport.",
+                "recommendation": "Ensure all elements use responsive widths and handle long content with word-wrap or overflow-x: auto.",
+                "screenshot": screenshot,
+                "user_impact": "Causes janky scrolling and potential content cut-off.",
+                "acceptance_criteria": [
+                    "No horizontal scrolling at tested width",
+                    "All elements are contained within the viewport",
+                ],
+            }
+            findings.append(finding)
+
+        # 3. Small Tap Targets
+        if res.get("tapTargets"):
+            finding = {
+                "title": f"Small Tap Targets on `{route}` ({vp})",
+                "route": route,
+                "viewport": vp,
+                "category": "Mobile UX",
+                "severity": "Medium",
+                "evidence": f"Found {len(res['tapTargets'])} interactive elements smaller than 44x44px.",
+                "recommendation": "Increase padding or dimensions of interactive elements to at least 44x44px for better mobile usability.",
+                "screenshot": screenshot,
+                "user_impact": "Makes interactive elements difficult to tap on a phone, leading to user frustration.",
+                "acceptance_criteria": [
+                    "All interactive elements meet the 44x44px minimum target size",
+                    "Adequate spacing between adjacent links/buttons",
+                ],
+            }
+            findings.append(finding)
+
+        # 4. Image issues
+        oversized_images = [
+            img
+            for img in res.get("images", [])
+            if img["naturalWidth"] > img["renderedWidth"] * 2 and img["naturalWidth"] > 1000
+        ]
+        if oversized_images:
+            finding = {
+                "title": f"Oversized Images on `{route}` ({vp})",
+                "route": route,
+                "viewport": vp,
+                "category": "Performance",
+                "severity": "Medium",
+                "evidence": f"Found {len(oversized_images)} images where natural size is significantly larger than rendered size.",
+                "recommendation": "Use responsive image sets (srcset) or serve optimized crops for smaller viewports.",
+                "screenshot": screenshot,
+                "user_impact": "Increases page load time and consumes excessive bandwidth.",
+                "acceptance_criteria": [
+                    "Images are appropriately sized for the viewport",
+                    "Lighthouse performance score is maintained or improved",
+                ],
+            }
+            findings.append(finding)
+
+        # 5. Above the Fold heuristics
+        atf = res.get("aboveTheFold")
+        if atf:
+            if atf.get("heroViewportPercentage", 0) > 80 and not atf.get("hasPrimaryCTA"):
+                finding = {
+                    "title": f"Poor Above-the-Fold Visibility on `{route}` ({vp})",
+                    "route": route,
+                    "viewport": vp,
+                    "category": "UX",
+                    "severity": "Medium",
+                    "evidence": f"Hero occupies {int(atf['heroViewportPercentage'])}% of viewport and no CTA is visible.",
+                    "recommendation": "Reduce hero height or move primary CTA higher to ensure it is visible above the fold.",
+                    "screenshot": screenshot,
+                    "user_impact": "Primary page purpose and next steps are unclear upon initial load.",
+                    "acceptance_criteria": [
+                        "Primary page purpose is clear above the fold",
+                        "Primary CTA is visible without scrolling",
+                    ],
+                }
+                findings.append(finding)
+
+    # List Findings in Report
+    if not findings:
+        report_lines.append("No major issues detected. ✅")
+    else:
+        # Sort findings by severity
+        severity_map = {"High": 0, "Medium": 1, "Low": 2}
+        findings.sort(key=lambda x: severity_map.get(x["severity"], 3))
+
+        for f in findings:
+            report_lines.append(f"### {f['title']}")
+            report_lines.append(f"- **Category:** {f['category']}")
+            report_lines.append(f"- **Severity:** {f['severity']}")
+            report_lines.append(f"- **Evidence:** {f['evidence']}")
+            report_lines.append(f"- **Screenshot:** `{f['screenshot']}`")
+            report_lines.append(f"- **Recommendation:** {f['recommendation']}\n")
+
+            # Generate Issue Draft
+            safe_title = (
+                f["title"].replace("/", "_").replace("`", "").replace("(", "").replace(")", "").replace(":", "")
+            )
+            issue_slug = f"{f['category']}-{safe_title}".lower().replace(" ", "-")
+            issue_path = os.path.join(issues_dir, f"{issue_slug}.md")
+            with open(issue_path, "w", encoding="utf-8") as issue_file:
+                issue_file.write(f"## Problem\n{f['title']}\n\n")
+                issue_file.write(f"## Route / viewport\n- Route: {f['route']}\n- Viewport: {f['viewport']}\n\n")
+                issue_file.write(f"## Evidence\n- {f['evidence']}\n- Screenshot: `{f['screenshot']}`\n\n")
+                issue_file.write(f"## User impact\n{f.get('user_impact', 'N/A')}\n\n")
+                issue_file.write(f"## Recommended fix\n{f['recommendation']}\n\n")
+                issue_file.write("## Acceptance criteria\n")
+                for ac in f.get("acceptance_criteria", []):
+                    issue_file.write(f"- [ ] {ac}\n")
+
+                # Add cross-viewport regression check
+                other = "mobile" if "desktop" in f["viewport"].lower() else "desktop"
+                issue_file.write(f"- [ ] No new {other} regressions\n")
+
+                issue_file.write(f"\n## Severity\n{f['severity']}\n")
+
+    report_path = os.path.join(artifacts_dir, "ux-audit-report.md")
+    with open(report_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(report_lines))
+
+    log_info(f"Report generated: {report_path}")
+    log_info(f"Issue drafts generated in: {issues_dir}")
+
+
+if __name__ == "__main__":
+    generate_report()

dev_tools/verify_infra.py

@@ -0,0 +1,91 @@
+# pylint: disable=missing-docstring,too-many-branches
+import os
+import re
+import subprocess
+import sys
+
+
+def check_shell_script(filepath):
+    """Performs static analysis on a shell script."""
+    findings = []
+
+    # 1. Syntax check (only for .sh files)
+    if filepath.endswith(".sh"):
+        try:
+            subprocess.run(["bash", "-n", filepath], check=True, capture_output=True, text=True)
+        except subprocess.CalledProcessError as e:
+            findings.append(f"Syntax error: {e.stderr.strip()}")
+            return findings
+
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except Exception as e:
+        findings.append(f"Could not read file: {e}")
+        return findings
+
+    # 2. Missing error handling in scripts (check first 10 lines for set -e, set -u, set -o pipefail)
+    uncommented_first_lines = [re.sub(r"#.*", "", line) for line in lines[:10]]
+    settings_content = " ".join(uncommented_first_lines)
+
+    missing_settings = []
+    if not re.search(r"set\s+-[^ \n]*e", settings_content):
+        missing_settings.append("set -e (errexit)")
+    if not re.search(r"set\s+-[^ \n]*u", settings_content):
+        missing_settings.append("set -u (nounset)")
+    if "pipefail" not in settings_content:
+        missing_settings.append("set -o pipefail")
+
+    if missing_settings and len(lines) > 5:
+        findings.append(f"Script lacks recommended settings in first 10 lines: {', '.join(missing_settings)}")
+
+    # 3. Pattern checks
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Hardcoded absolute paths (excluding common system ones)
+        if re.search(
+            r'(^|\s|["\'])/(?!(bin|usr/bin|dev|proc|tmp|etc|lib|var/lib|sys|usr/sbin|sbin|var/run))[a-zA-Z0-9]',
+            line,
+        ):
+            if not re.search(r"[0-9]\s*/\s*[0-9]", line):  # Avoid flagging division
+                findings.append(f"Line {i+1}: Potential hardcoded absolute path: {stripped}")
+
+        # Unquoted variables in risky commands - SIMPLIFIED heuristic
+        # We flag cases where a variable expansion ($VAR or ${VAR}) is used in a risky command
+        # without any quotes on that line. This is a simple signal.
+        if any(cmd in stripped for cmd in ["rm ", "cp ", "mv ", "ls "]):
+            if "$" in stripped and not any(q in stripped for q in ['"', "'"]):
+                findings.append(f"Line {i+1}: Potential unquoted variable in risky command: {stripped}")
+
+    if len(lines) > 20:
+        findings.append("Note: For complex shell scripts, please run 'shellcheck' for deeper analysis.")
+
+    return findings
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python3 verify_infra.py <filepath>")
+        sys.exit(1)
+
+    filepath = sys.argv[1]
+    if not os.path.exists(filepath):
+        print(f"File not found: {filepath}")
+        sys.exit(1)
+
+    findings = check_shell_script(filepath)
+    if findings:
+        print(f"Infrastructure violations found in {filepath}:")
+        for f in findings:
+            print(f"- {f}")
+        sys.exit(1)
+    else:
+        print(f"No infrastructure violations found in {filepath}.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

dev_tools/verify_versions.py

@@ -0,0 +1,191 @@
+# pylint: disable=invalid-name,line-too-long,missing-docstring,no-else-break,no-value-for-parameter,too-many-branches,too-many-locals,too-many-statements
+import json
+import os
+import re
+import sys
+from typing import Dict, List
+
+import click
+from dev_tools.utils import (
+    compare_versions,
+    fetch_latest_gh_action,
+    fetch_latest_node,
+    fetch_latest_npm,
+    get_stack_versions,
+)
+
+
+def parse_diff(diff_text: str) -> List[Dict]:
+    """Parses a git diff to find version changes."""
+    changes = []
+    current_file = None
+
+    # Regex patterns
+    ACTION_PATTERN = re.compile(r"uses:\s+([\w\-/]+)@([\w\.]+)")
+    PKG_JSON_VERSION_PATTERN = re.compile(r'"(node|pnpm|[\w\-\./@]+)":\s*"([\d\.\^x~<>=\| v]+)"')
+    PM_PATTERN = re.compile(r'"packageManager":\s*"pnpm@([\d\.]+)"')
+
+    # Files we care about
+    SENSITIVE_FILES = [".nvmrc", ".node-version", "package.json"]
+    SENSITIVE_DIRS = [".github/workflows/"]
+
+    hunks = re.split(r"^(?=--- )", diff_text, flags=re.MULTILINE)
+    for hunk in hunks:
+        if not hunk.strip():
+            continue
+
+        lines = hunk.splitlines()
+        current_file = None
+        for line in lines:
+            if line.startswith("--- a/"):
+                current_file = line[6:]
+                break
+            elif line.startswith("+++ b/"):
+                current_file = line[6:]
+                break
+
+        if not current_file:
+            continue
+
+        is_sensitive = current_file in SENSITIVE_FILES or any(current_file.startswith(sd) for sd in SENSITIVE_DIRS)
+        if not is_sensitive:
+            continue
+
+        removals = {}  # name -> version
+        additions = {}  # name -> version
+
+        for line in lines:
+            if line.startswith("--- ") or line.startswith("+++ ") or line.startswith("@@ "):
+                continue
+
+            if line.startswith("-"):
+                content = line[1:].strip()
+                # Check Actions
+                m = ACTION_PATTERN.search(content)
+                if m:
+                    removals[m.group(1)] = m.group(2)
+                # Check Dependencies
+                m = PKG_JSON_VERSION_PATTERN.search(content)
+                if m:
+                    removals[m.group(1)] = m.group(2)
+                # Check pnpm
+                m = PM_PATTERN.search(content)
+                if m:
+                    removals["pnpm"] = m.group(1)
+                # Check node files
+                if current_file in [".nvmrc", ".node-version"]:
+                    removals["node"] = content.replace("v", "")
+
+            elif line.startswith("+"):
+                content = line[1:].strip()
+                m = ACTION_PATTERN.search(content)
+                if m:
+                    additions[m.group(1)] = m.group(2)
+                m = PKG_JSON_VERSION_PATTERN.search(content)
+                if m:
+                    additions[m.group(1)] = m.group(2)
+                m = PM_PATTERN.search(content)
+                if m:
+                    additions["pnpm"] = m.group(1)
+                if current_file in [".nvmrc", ".node-version"]:
+                    additions["node"] = content.replace("v", "")
+
+        # Correlate changes
+        for name, new_v in additions.items():
+            old_v = removals.get(name, "unknown")
+            type_val = "action" if "/" in name and "pnpm" not in name else "dependency"
+            if name == "node" or current_file in [".nvmrc", ".node-version"]:
+                type_val = "runtime"
+
+            changes.append({"file": current_file, "type": type_val, "name": name, "old": old_v, "new": new_v})
+
+    return changes
+
+
+def verify_changes(changes: List[Dict]) -> List[Dict]:
+    """Verifies changes against HEAD and registries."""
+    findings = []
+    stack = get_stack_versions()
+
+    for c in changes:
+        # 1. Compare against HEAD (Downgrade detection)
+        head_v = stack.get(c["name"])
+        if not head_v and c["name"] == "node":
+            head_v = stack.get("node")
+        if not head_v and c["name"] == "pnpm":
+            head_v = stack.get("pnpm")
+
+        if head_v:
+            if compare_versions(c["new"], head_v) < 0:
+                findings.append(
+                    {
+                        "severity": "error",
+                        "file": c["file"],
+                        "message": f"Version downgrade detected for {c['name']}: {head_v} -> {c['new']}",
+                        "type": "downgrade",
+                    }
+                )
+
+        # 2. Compare against Latest (Outdated detection - optional warning)
+        latest = None
+        if c["name"] == "node":
+            latest = fetch_latest_node()
+        elif c["type"] == "action":
+            latest = fetch_latest_gh_action(c["name"])
+        elif c["name"] in ["pnpm"] or c["type"] == "dependency":
+            latest = fetch_latest_npm(c["name"])
+
+        if latest:
+            if compare_versions(c["new"], latest) < 0:
+                findings.append(
+                    {
+                        "severity": "warn",
+                        "file": c["file"],
+                        "message": f"Proposed version for {c['name']} ({c['new']}) is outdated. Latest is {latest}.",
+                        "type": "outdated",
+                    }
+                )
+
+        # 3. Node.js Hard Block
+        if c["name"] == "node":
+            # Only trigger hard block if the version is ACTUALLY changing from HEAD
+            if head_v and compare_versions(c["new"], head_v) != 0:
+                if os.environ.get("ALLOW_NODE_VERSION_CHANGE") != "true":
+                    findings.append(
+                        {
+                            "severity": "error",
+                            "file": c["file"],
+                            "message": f"Hard block: Node.js version modification detected ({head_v} -> {c['new']}). Modification is forbidden unless ALLOW_NODE_VERSION_CHANGE=true.",
+                            "type": "hard_block",
+                        }
+                    )
+
+    return findings
+
+
+@click.command()
+@click.argument("diff_input")
+def main(diff_input):
+    """Verifies version changes in a diff."""
+    if os.path.exists(diff_input):
+        with open(diff_input, "r", encoding="utf-8") as f:
+            diff_text = f.read()
+    else:
+        diff_text = diff_input
+
+    changes = parse_diff(diff_text)
+    findings = verify_changes(changes)
+
+    if findings:
+        print(json.dumps(findings, indent=2))
+        # Exit with error code if any 'error' severity exists
+        if any(f["severity"] == "error" for f in findings):
+            sys.exit(1)
+    else:
+        print(json.dumps([], indent=2))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()