@diff-review-system/drs 4.0.0-rc.4 → 4.1.0

package/.pi/workflows/github-pr-review.yaml

@@ -1,19 +1,94 @@
 name: github-pr-review
-description: Review a GitHub pull request
+description: Review a GitHub pull request, optionally posting a description, DRS comments, a visual HTML explainer, and a stacked fix PR
+metadata:
+  kind: review
+  tags: [review, github, pull-request]
+  review:
+    source: github-pr
+    diff: true
+    issues: true
 inputs:
-  owner: ""
-  repo: ""
-  pr: ""
+  owner:
+    type: string
+    required: true
+    description: GitHub repository owner
+  repo:
+    type: string
+    required: true
+    description: GitHub repository name
+  pr:
+    type: number
+    required: true
+    description: Pull request number
+  describe:
+    type: boolean
+    default: false
+    description: Generate and post a PR description
+  post:
+    type: boolean
+    default: false
+    description: Post DRS review comments to the PR
+  visual:
+    type: boolean
+    default: false
+    description: Generate a visual HTML explainer artifact
+  fix:
+    type: boolean
+    default: false
+    description: Attempt to fix qualifying review findings
+  fixMode:
+    type: enum
+    values: [stacked, internal]
+    default: stacked
+    description: Create stacked fix PR or push verified fixes to the source branch
+  fixSeverity:
+    type: enum
+    values: [critical, high, medium, low]
+    default: high
+    description: Minimum finding severity to fix
+  fixMinIssues:
+    type: number
+    default: 1
+    description: Minimum matching issues required before fixing
+  fixBranchPrefix:
+    type: string
+    default: drs-fix/pr-
+  fixCreateChangeRequest:
+    type: boolean
+    default: false
+  fixMaxIterations:
+    type: number
+    default: 3
+  allowStackedSource:
+    type: boolean
+    default: false
+  fixDraft:
+    type: boolean
+    default: false
+  visualOutputPath:
+    type: string
+    default: .drs/visual-pr-explainer.html
+output: review
 nodes:
   change:
     action: change-source
     with:
       type: github-pr
-      owner: "{{inputs.owner}}"
-      repo: "{{inputs.repo}}"
-      pr: "{{inputs.pr}}"
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
     output: change
 
+  describe:
+    action: describe
+    needs:
+      - change
+    if: inputs.describe == true
+    with:
+      source: change
+      post: true
+    output: description
+
   review:
     action: review
     needs:
@@ -21,3 +96,275 @@ nodes:
     with:
       source: change
     output: review
+
+  visual:
+    agent: visual/pr-explainer
+    needs:
+      - change
+      - review
+    if: inputs.visual == true
+    input: |
+      Generate a visual PR explainer HTML artifact.
+
+      Output path: {{inputs.visualOutputPath}}
+      Slide mode: false
+
+      Use the supplied DRS change-source context. If important file diffs are omitted or summarized, use git_diff for those files before explaining them.
+
+      DRS change-source context:
+      {{artifacts.change}}
+
+      DRS review result:
+      {{artifacts.review}}
+    writes: '{{inputs.visualOutputPath}}'
+    output: visualExplainer
+
+  post-comments:
+    action: post-review-comments
+    needs:
+      - review
+    if: inputs.post == true
+    with:
+      source: change
+      review: review
+    output: postedReview
+
+  stack-guard:
+    action: stack-guard
+    needs:
+      - change
+      - review
+    if: inputs.fix == true
+    with:
+      source: change
+      allowStackedSource: '{{inputs.allowStackedSource}}'
+    output: stackGuard
+
+  fix-threshold:
+    action: review-threshold
+    needs:
+      - review
+      - stack-guard
+    if: artifacts.stackGuard.allowed == true
+    with:
+      review: review
+      severity: '{{inputs.fixSeverity}}'
+      minIssues: '{{inputs.fixMinIssues}}'
+    output: reviewThreshold
+
+  fix-branch:
+    action: git-branch
+    needs:
+      - fix-threshold
+    if: artifacts.reviewThreshold.matched == true
+    with:
+      name: '{{inputs.fixBranchPrefix}}{{inputs.pr}}'
+      force: true
+    output: fixBranch
+
+  fix-issues:
+    agent: task/review-issue-fixer
+    needs:
+      - fix-branch
+      - review
+    input: |
+      Fix actionable issues from this DRS review artifact for GitHub PR #{{inputs.pr}}.
+
+      Only fix findings at or above severity {{inputs.fixSeverity}} unless a lower-severity issue is directly required by such a fix.
+
+      Review artifact path: {{artifacts.reviewArtifact.path}}
+
+      Use the read_artifact tool with this path to get the finding manifest, then pull full details for specific findings by id. Do not assume the review JSON is in this prompt — call the tool.
+
+      Current PR change source files (read these as needed):
+      {{artifacts.change.files}}
+
+      Use the drs_check tool after making changes to run configured validation checks before returning.
+    output: fixes
+
+  fix-change:
+    action: change-source
+    needs:
+      - fix-issues
+    if: inputs.fixMode == internal
+    with:
+      type: local
+      staged: false
+    output: fixChange
+
+  stage-fixes:
+    action: git-add
+    needs:
+      - fix-change
+    if: inputs.fixMode == internal
+    with:
+      paths: '.'
+    output: stagedFixes
+
+  verification-change:
+    action: change-source
+    needs:
+      - fix-change
+    if: inputs.fixMode == internal
+    with:
+      type: fix-verification
+      source: change
+      fixChange: fixChange
+    output: verificationChange
+
+  re-review:
+    action: review
+    needs:
+      - verification-change
+    if: inputs.fixMode == internal
+    with:
+      source: verificationChange
+      reviewArtifact: reviewArtifact
+      severity: '{{inputs.fixSeverity}}'
+    output: reReview
+
+  verify-fix:
+    action: verify-fix
+    needs:
+      - re-review
+      - fix-change
+    if: inputs.fixMode == internal
+    with:
+      artifact: reviewArtifact
+      review: reReview
+      fixChange: fixChange
+      severity: '{{inputs.fixSeverity}}'
+      minIssues: '1'
+    output: reviewArtifact
+
+  fix-loop:
+    control: loop
+    needs:
+      - verify-fix
+    if: artifacts.verify-fix.shouldContinue == true && inputs.fixMode == internal
+    target: fix-issues
+    exit: post-fix-status-internal
+    maxIterations: '{{inputs.fixMaxIterations}}'
+    onMaxIterations: exit
+
+  post-fix-status-internal:
+    action: post-fix-status
+    needs:
+      - verify-fix
+    if: inputs.fixMode == internal
+    with:
+      platform: github
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
+      source: change
+      reviewArtifact: reviewArtifact
+      fixReview: reReview
+      fixChange: fixChange
+      severity: '{{inputs.fixSeverity}}'
+      marker: drs-fix-status
+    output: fixStatus
+
+  commit-internal-fix:
+    action: git-commit
+    needs:
+      - post-fix-status-internal
+    if: artifacts.verify-fix.fixFiles > 0
+    with:
+      message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
+      paths: '.'
+    output: internalFixCommit
+
+  push-internal-fix:
+    action: git-push
+    needs:
+      - commit-internal-fix
+    with:
+      branch: HEAD
+      remoteBranch: '{{artifacts.change.context.pullRequest.sourceBranch}}'
+      setUpstream: false
+    output: internalFixPush
+
+  fix-diff:
+    action: has-diff
+    needs:
+      - fix-issues
+    if: inputs.fixMode != internal
+    output: fixDiff
+
+  fix-commit:
+    action: git-commit
+    needs:
+      - fix-diff
+    if: artifacts.fixDiff.changed == true && inputs.fixCreateChangeRequest == true && inputs.fixMode != internal
+    with:
+      message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
+      paths: '.'
+    output: fixCommit
+
+  fix-push:
+    action: git-push
+    needs:
+      - fix-commit
+    with:
+      branch: '{{inputs.fixBranchPrefix}}{{inputs.pr}}'
+    output: fixPush
+
+  create-fix-pr:
+    action: create-change-request
+    needs:
+      - fix-push
+    with:
+      platform: github
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      sourceBranch: '{{inputs.fixBranchPrefix}}{{inputs.pr}}'
+      targetBranch: '{{artifacts.change.context.pullRequest.sourceBranch}}'
+      title: 'fix: address DRS review issues for PR #{{inputs.pr}}'
+      draft: '{{inputs.fixDraft}}'
+      body: |
+        Automated DRS fix stacked on PR #{{inputs.pr}} from the main github-pr-review workflow.
+
+        Threshold: {{inputs.fixSeverity}}, minimum issues: {{inputs.fixMinIssues}}
+        Review artifact: {{artifacts.reviewArtifact.path}}
+
+        <!-- drs-stack-source: github:{{inputs.owner}}/{{inputs.repo}}#{{inputs.pr}} -->
+        <!-- drs-stack-kind: fix -->
+    output: changeRequest
+
+  notify-fix-pr:
+    action: post-comment
+    needs:
+      - create-fix-pr
+    with:
+      platform: github
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
+      marker: drs-stacked-fix-notification
+    input: |
+      🔧 DRS created a stacked fix PR: {{artifacts.changeRequest.url}}
+
+      The fix addresses {{inputs.fixSeverity}}-priority review findings from this PR's review run.
+
+      <!-- drs-stacked-fix-notification -->
+
+  post-fix-status-stacked:
+    action: post-fix-status
+    needs:
+      - create-fix-pr
+      - review
+    with:
+      platform: github
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
+      source: change
+      reviewArtifact: reviewArtifact
+      severity: '{{inputs.fixSeverity}}'
+      stackedPrUrl: '{{artifacts.changeRequest.url}}'
+      marker: drs-fix-status
+    output: fixStatus
+
+  done:
+    control: end

package/.pi/workflows/github-pr-show-changes.yaml

@@ -1,18 +1,18 @@
 name: github-pr-show-changes
 description: Show the review context for a GitHub pull request
 inputs:
-  owner: ""
-  repo: ""
-  pr: ""
-  file: ""
+  owner: ''
+  repo: ''
+  pr: ''
+  file: ''
 nodes:
   change:
     action: change-source
     with:
       type: github-pr
-      owner: "{{inputs.owner}}"
-      repo: "{{inputs.repo}}"
-      pr: "{{inputs.pr}}"
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
     output: change
 
   context:
@@ -21,5 +21,5 @@ nodes:
       - change
     with:
       source: change
-      file: "{{inputs.file}}"
+      file: '{{inputs.file}}'
     output: reviewContext

package/.pi/workflows/github-pr-update-agents-md-stacked.yaml

@@ -0,0 +1,103 @@
+name: github-pr-update-agents-md-stacked
+description: Update agent guidance for a GitHub PR and open a stacked PR when warranted
+inputs:
+  owner: ''
+  repo: ''
+  pr: ''
+  paths: 'AGENTS.md,CLAUDE.md,.github/copilot-instructions.md'
+  branchPrefix: 'drs-guidance/pr-'
+  allowStackedSource: 'false'
+  draft: 'false'
+output: changeRequest
+nodes:
+  change:
+    action: change-source
+    with:
+      type: github-pr
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
+    output: change
+
+  guard:
+    action: stack-guard
+    needs:
+      - change
+    with:
+      source: change
+      allowStackedSource: '{{inputs.allowStackedSource}}'
+    output: stackGuard
+
+  branch:
+    action: git-branch
+    needs:
+      - guard
+    if: '{{artifacts.stackGuard.allowed}} == true'
+    with:
+      name: '{{inputs.branchPrefix}}{{inputs.pr}}'
+      force: true
+    output: branch
+
+  update-guidance:
+    agent: task/agents-md-updater
+    needs:
+      - change
+      - branch
+    input: |
+      Decide whether this GitHub PR warrants an update to repository coding-agent guidance.
+
+      Guidance paths to consider: {{inputs.paths}}
+
+      If no durable guidance update is warranted, leave files unchanged and say so.
+
+      GitHub PR change source:
+      {{artifacts.change}}
+    output: guidance
+
+  diff:
+    action: has-diff
+    needs:
+      - update-guidance
+    with:
+      paths: '{{inputs.paths}}'
+    output: guidanceDiff
+
+  commit:
+    action: git-commit
+    needs:
+      - diff
+    if: '{{artifacts.guidanceDiff.changed}} == true'
+    with:
+      message: 'docs: update agent guidance for PR #{{inputs.pr}}'
+      paths: '{{inputs.paths}}'
+    output: commit
+
+  push:
+    action: git-push
+    needs:
+      - commit
+    with:
+      branch: '{{inputs.branchPrefix}}{{inputs.pr}}'
+    output: push
+
+  create:
+    action: create-change-request
+    needs:
+      - push
+    with:
+      platform: github
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      sourceBranch: '{{inputs.branchPrefix}}{{inputs.pr}}'
+      targetBranch: '{{artifacts.change.context.pullRequest.sourceBranch}}'
+      title: 'docs: update agent guidance for PR #{{inputs.pr}}'
+      draft: '{{inputs.draft}}'
+      body: |
+        Automated DRS guidance update stacked on PR #{{inputs.pr}}.
+
+        <!-- drs-stack-source: github:{{inputs.owner}}/{{inputs.repo}}#{{inputs.pr}} -->
+        <!-- drs-stack-kind: guidance -->
+    output: changeRequest
+
+  done:
+    control: end

package/.pi/workflows/github-pr-visual-explain.yaml

@@ -0,0 +1,80 @@
+name: github-pr-visual-explain
+description: Generate a visual HTML explainer artifact for a GitHub pull request
+inputs:
+  owner: ''
+  repo: ''
+  pr: ''
+  outputPath: '.drs/visual-pr-explainer.html'
+  slides: 'false'
+output: visualExplainer
+nodes:
+  change:
+    action: change-source
+    with:
+      type: github-pr
+      owner: '{{inputs.owner}}'
+      repo: '{{inputs.repo}}'
+      pr: '{{inputs.pr}}'
+    output: change
+
+  review-artifact:
+    action: artifact-exists
+    needs:
+      - change
+    with:
+      kind: review
+      source: change
+    output: reviewArtifactStatus
+
+  load-review-artifact:
+    action: load-artifact
+    needs:
+      - review-artifact
+    if: artifacts.reviewArtifactStatus.exists == true
+    with:
+      kind: review
+      source: change
+    output: reviewArtifact
+
+  visual-with-review:
+    agent: visual/pr-explainer
+    needs:
+      - change
+      - load-review-artifact
+    if: artifacts.reviewArtifactStatus.exists == true
+    input: |
+      Generate a visual PR explainer HTML artifact.
+
+      Output path: {{inputs.outputPath}}
+      Slide mode: {{inputs.slides}}
+
+      Use the supplied DRS change-source context. If important file diffs are omitted or summarized, use git_diff for those files before explaining them.
+
+      DRS change-source context:
+      {{artifacts.change}}
+
+      Current DRS review artifact path: {{artifacts.reviewArtifact.path}}
+
+      Use the read_artifact tool with this path to include confirmed DRS findings in a clearly labeled section. Do not assume the review JSON is in this prompt.
+    writes: '{{inputs.outputPath}}'
+    output: visualExplainer
+
+  visual:
+    agent: visual/pr-explainer
+    needs:
+      - review-artifact
+    if: artifacts.reviewArtifactStatus.exists == false
+    input: |
+      Generate a visual PR explainer HTML artifact.
+
+      Output path: {{inputs.outputPath}}
+      Slide mode: {{inputs.slides}}
+
+      Use the supplied DRS change-source context. If important file diffs are omitted or summarized, use git_diff for those files before explaining them.
+
+      DRS change-source context:
+      {{artifacts.change}}
+
+      No current DRS review artifact exists for this PR. Label the artifact as a PR explainer with no DRS findings included.
+    writes: '{{inputs.outputPath}}'
+    output: visualExplainer

package/.pi/workflows/gitlab-mr-describe.yaml

@@ -1,15 +1,17 @@
 name: gitlab-mr-describe
-description: Generate a GitLab merge request description
+description: Generate a GitLab merge request description, optionally posting it
 inputs:
-  project: ""
-  mr: ""
+  project: ''
+  mr: ''
+  post: 'false'
+output: description
 nodes:
   change:
     action: change-source
     with:
       type: gitlab-mr
-      project: "{{inputs.project}}"
-      mr: "{{inputs.mr}}"
+      project: '{{inputs.project}}'
+      mr: '{{inputs.mr}}'
     output: change
 
   describe:
@@ -18,4 +20,5 @@ nodes:
       - change
     with:
       source: change
+      post: '{{inputs.post}}'
     output: description