Arvind2006/jenkins-error-explainer

1# explain_error.py2 3from extract_error_features import extract_error_features4from retrieve_docs import retrieve_docs5 6SYSTEM_PROMPT = """7You are a Jenkins CI/CD expert.8 9Explain the Jenkins error using ONLY the provided documentation context.10If the documentation does not clearly explain the error, say so explicitly.11 12Output format:13 14Error Summary:15<short explanation>16 17Likely Causes:18- cause 119- cause 220 21Relevant Documentation:22- link or source file23"""24 25def explain_error(log_text: str):26    features = extract_error_features(log_text)27    category = features["category"]28 29    retrieved = retrieve_docs(category)30 31    explanation = {32        "error_category": category,33        "summary": "",34        "likely_causes": [],35        "references": []36    }37 38    # Heuristic explanation (v1, deterministic)39    if category == "groovy_syntax_error":40        explanation["summary"] = (41            "The pipeline failed due to a Groovy syntax error, "42            "most likely caused by an invalid or incomplete Jenkinsfile."43        )44        explanation["likely_causes"] = [45            "Missing or mismatched braces in the Jenkinsfile",46            "Invalid declarative pipeline structure"47        ]48 49    elif category == "missing_agent":50        explanation["summary"] = (51            "The pipeline attempted to execute a step that requires a node, "52            "but no agent was allocated."53        )54        explanation["likely_causes"] = [55            "Using 'agent none' without defining a stage-level agent",56            "Executing node-dependent steps without a workspace"57        ]58 59    elif category == "no_node_available":60        explanation["summary"] = (61            "The pipeline could not be scheduled because no Jenkins node "62            "matched the requested label."63        )64        explanation["likely_causes"] = [65            "The specified node label does not exist",66            "All matching nodes are offline or busy"67        ]68 69    elif category == "missing_plugin":70        explanation["summary"] = (71            "The pipeline referenced a step that is not available, "72            "indicating a missing or uninstalled plugin."73        )74        explanation["likely_causes"] = [75            "Required plugin is not installed",76            "Incorrect step name in the Jenkinsfile"77        ]78 79    elif category == "missing_credentials":80        explanation["summary"] = (81            "The pipeline referenced credentials that do not exist in Jenkins."82        )83        explanation["likely_causes"] = [84            "Credentials ID is incorrect or misspelled",85            "Credentials were not configured in Jenkins"86        ]87 88    elif category == "file_not_found":89        explanation["summary"] = (90            "The pipeline attempted to access a file that does not exist "91            "in the workspace."92        )93        explanation["likely_causes"] = [94            "File path is incorrect",95            "File was not generated or checked out"96        ]97 98    elif category == "git_authentication_error":99        explanation["summary"] = (100            "Jenkins failed to authenticate with the Git repository during checkout."101        )102        explanation["likely_causes"] = [103            "Invalid or missing Git credentials",104            "Repository requires token-based authentication"105        ]106 107    else:108        explanation["summary"] = (109            "The error could not be confidently explained using the available documentation."110        )111 112    for r in retrieved:113        explanation["references"].append(114            f"{r['meta']['source_file']} ({r['meta']['source']})"115        )116    if not retrieved:117        explanation["summary"] = (118            "No relevant Jenkins documentation was found for this error. "119            "The error may be plugin-specific or outside the current scope."120        )121        explanation["likely_causes"] = []122        explanation["references"] = []123 124    return explanation125 126 127