Class DoctorService

java.lang.Object
com.shaft.mcp.DoctorService
@Service public class DoctorService extends Object
MCP adapter for deterministic SHAFT Doctor analysis with optional configured provider advisory.

  • Constructor Details

    • DoctorService

      public DoctorService()
      Creates the default local MCP Doctor service.

  • Method Details

    • analyzeFailedAllure

      @Tool(name="doctor_analyze_failed_allure", description="analyzes failed Allure results and returns deterministic actions plus copy-paste code blocks; accepts allure-results directories, individual *-result.json files, or a SHAFT single-file AllureReport.html; when allureResultPaths is empty, automatically analyzes the newest such evidence found in the workspace; optional backend (web|playwright, defaults to web) selects the generated remediation snippets' engine, absorbing playwright_doctor_analyze_failed_allure") public McpAnalysisReport analyzeFailedAllure(List<String> allureResultPaths, List<String> historicalBundlePaths, String outputDirectory, boolean includeScreenshots, boolean includePageSnapshots, int minimumAllureResults, String repositoryRoot, List<String> allowedSourcePaths, boolean useAi, boolean allowLocalAi, boolean allowRemoteAi, String driverVariableName, @ToolParam(required=false) String backend)
      Analyzes failed Allure evidence and returns deterministic remediation plus optional AI advisory snippets.
      Parameters:
      allureResultPaths - Allure result directories or files inside the MCP workspace
      historicalBundlePaths - optional older Doctor bundles inside the MCP workspace
      outputDirectory - output directory inside the MCP workspace
      includeScreenshots - explicit approval to retain local screenshot evidence
      includePageSnapshots - explicit approval to retain local page-snapshot evidence
      minimumAllureResults - minimum populated Allure result count
      repositoryRoot - optional repository root inside the MCP workspace
      allowedSourcePaths - optional repository-relative source paths approved for AI SOURCE evidence
      useAi - whether to request optional provider snippet fallback
      allowLocalAi - local provider consent for this request
      allowRemoteAi - remote provider consent for this request
      driverVariableName - Java driver variable name used in snippets
      Returns:
      deterministic diagnosis, action records, code blocks, report paths, and provider metadata

    • suggestFix

      @Tool(name="doctor_suggest_fix", description="returns copy-paste remediation code blocks from an existing SHAFT Doctor report; optional backend (web|playwright, defaults to web) selects the generated snippets' engine, absorbing playwright_doctor_suggest_fix") public McpAnalysisReport suggestFix(String jsonReportPath, String repositoryRoot, List<String> allowedSourcePaths, boolean useAi, boolean allowLocalAi, boolean allowRemoteAi, String driverVariableName, @ToolParam(required=false) String backend)
      Rebuilds MCP remediation actions and code blocks from an existing Doctor JSON report.
      Parameters:
      jsonReportPath - Doctor JSON report path inside the MCP workspace
      repositoryRoot - optional repository root inside the MCP workspace
      allowedSourcePaths - optional repository-relative source paths approved for AI SOURCE evidence
      useAi - whether to request optional provider snippet fallback
      allowLocalAi - local provider consent for this request
      allowRemoteAi - remote provider consent for this request
      driverVariableName - Java driver variable name used in snippets
      backend - optional codegen target ("web" default | "playwright"); absorbs playwright_doctor_suggest_fix
      Returns:
      deterministic diagnosis, action records, code blocks, report paths, and provider metadata

    • analyze

      public DoctorAnalysisSummary analyze(List<String> inputPaths, List<String> historicalBundlePaths, List<String> allowedRoots, String outputDirectory, boolean includeScreenshots, boolean includePageSnapshots, int minimumAllureResults)
      Analyzes explicitly allowed local evidence and optionally appends a configured provider advisory.
      Parameters:
      inputPaths - explicit evidence files or directories
      historicalBundlePaths - optional older Doctor bundle files
      allowedRoots - roots that all readable inputs must remain within
      outputDirectory - report destination inside an allowed root
      includeScreenshots - explicit screenshot retention approval
      includePageSnapshots - explicit page-source or snapshot retention approval
      minimumAllureResults - minimum valid Allure result count expected
      Returns:
      deterministic diagnosis and local report paths

    • proposeFix

      public DoctorRepairProposalResult proposeFix(String repositoryRoot, String baseSha, String diagnosisPath, String evidenceBundlePath, String issueReference, List<String> allowedPaths, List<DoctorRepairRequest.FilePatch> patches, List<List<String>> validationCommands, boolean networkValidationApproved, String outputDirectory, boolean useAi)
      Creates a repair proposal in an isolated worktree without writing to GitHub.
      Parameters:
      repositoryRoot - approved Git repository root
      baseSha - exact approved base commit
      diagnosisPath - Doctor diagnosis or combined report JSON
      evidenceBundlePath - optional evidence bundle
      issueReference - linked issue or session
      allowedPaths - approved repository-relative repair scope
      patches - reviewed structured patches
      validationCommands - tokenized Maven validation commands
      networkValidationApproved - whether Maven validation may use the network
      outputDirectory - proposal manifest directory
      useAi - whether to request an optional provider-generated patch instead
      Returns:
      complete proposal and optional provider status

    • proposeHealedLocator

      @Tool(name="doctor_propose_healed_locator", description="maps a verified SHAFT Heal report to one reviewable locator patch without editing source or publishing") public HealingLocatorProposal proposeHealedLocator(String repositoryRoot, String healingReportPath, String sourcePath, boolean sourcePatchConsent, String outputDirectory)
      Creates a proposal-only locator patch from a verified SHAFT Heal report.
      Parameters:
      repositoryRoot - approved Git repository root
      healingReportPath - verified SHAFT Heal report JSON
      sourcePath - repository-relative Java source file
      sourcePatchConsent - explicit proposal consent
      outputDirectory - proposal artifact directory
      Returns:
      reviewable locator proposal and structured Doctor patch

    • proposeAdvisoryLocator

      @Tool(name="doctor_propose_advisory_locator", description="maps a low-trust SHAFT Heal report to one reviewable advisory locator comment proposal without editing, replacing, or publishing") public HealingLocatorProposal proposeAdvisoryLocator(String repositoryRoot, String healingReportPath, String sourcePath, boolean sourcePatchConsent, String outputDirectory)
      Creates an advisory-only, unconfirmed locator patch proposal from a low-trust (BELOW_THRESHOLD) SHAFT Heal report (issue #4194).

      Unlike proposeHealedLocator(String, String, String, boolean, String), this never requires a confirmed recovery -- a low-confidence best candidate is exactly the signal this exists for. The resulting patch only adds a review comment; it never replaces the existing locator.

      Parameters:
      repositoryRoot - approved Git repository root
      healingReportPath - low-trust SHAFT Heal report JSON
      sourcePath - repository-relative Java source file
      sourcePatchConsent - explicit proposal consent
      outputDirectory - proposal artifact directory
      Returns:
      reviewable advisory proposal and structured Doctor patch

    • publishDraftPr

      public RepairPublicationResult publishDraftPr(String manifestPath, boolean approved, String approvalToken, boolean overrideFailedValidation, String overrideRationale, String title)
      Publishes an approved proposal as a draft pull request only.
      Parameters:
      manifestPath - persisted proposal manifest
      approved - explicit publication approval
      approvalToken - exact proposal token
      overrideFailedValidation - explicit failed-validation override
      overrideRationale - required override rationale
      title - optional draft pull-request title
      Returns:
      draft publication details