microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
.github/instructions/coding-standards/code-review/diff-computation.instructions.md
106lines · modecode
| 1 | --- |
| 2 | description: "Code review diff computation: branch detection, scope locking, large-diff handling, and non-source filtering" |
| 3 | applyTo: "**/.github/agents/coding-standards/**, **/.github/prompts/coding-standards/**" |
| 4 | --- |
| 5 | |
| 6 | # Diff Computation Protocol |
| 7 | |
| 8 | Obtain the diff before reading any source files. Use the decision tree below to determine the appropriate method, then apply scope rules and large diff handling. |
| 9 | |
| 10 | ## Decision Tree |
| 11 | |
| 12 | Run `git branch --show-current` and `git status --short` to determine context. Match the first applicable case: |
| 13 | |
| 14 | 1. **Branch review** (user explicitly requests a specific branch or PR, or is on a feature branch that is not `main` and not detached HEAD): follow the Feature Branch Diff section. The pr-reference skill captures committed changes; a working-tree supplement captures staged, unstaged, and untracked changes. If the user says "review the PR" while on `main` or detached HEAD without naming a branch, PR, or commit, ask which branch or PR they want reviewed, then route to this case or to the Specific Commit section as appropriate. |
| 15 | 2. **Local uncommitted changes on `main` or detached HEAD** (not on a feature branch, but edits exist that are not yet committed): follow the Uncommitted Changes section. |
| 16 | 3. **Selected code or `#file` references** (user selects code in the editor or references `#file:path/to/file.ext`): follow the Selected Code section. |
| 17 | 4. **Specific commit review** (user asks to review a particular commit): follow the Specific Commit section. |
| 18 | 5. **No reviewable content**: inform the user that no diff could be determined and stop. |
| 19 | |
| 20 | ## Feature Branch Diff |
| 21 | |
| 22 | Invoke the **pr-reference** skill to compute the diff. The skill handles branch detection, merge-base resolution, file listing, non-source exclusions, and large diff chunking. |
| 23 | |
| 24 | 1. Generate the structured diff: |
| 25 | |
| 26 | ```bash |
| 27 | generate.sh --base-branch auto --merge-base --exclude-ext min.js,min.css,map |
| 28 | ``` |
| 29 | |
| 30 | 2. Get the changed file list: |
| 31 | |
| 32 | ```bash |
| 33 | list-changed-files.sh --exclude-type deleted --format plain |
| 34 | ``` |
| 35 | |
| 36 | 3. For large diffs, use chunk planning and batched analysis: |
| 37 | |
| 38 | ```bash |
| 39 | read-diff.sh --info # chunk count and size summary |
| 40 | read-diff.sh --chunk N # read chunk N |
| 41 | ``` |
| 42 | |
| 43 | If `list-changed-files.sh` returns an empty list, stop and report "no reviewable content" per Decision Tree case 5. |
| 44 | |
| 45 | Pass the diff output and file list as pre-computed input to the review agent so it skips its own scope detection. |
| 46 | |
| 47 | ## Uncommitted Changes |
| 48 | |
| 49 | * Unstaged: `git diff HEAD` |
| 50 | * Staged: `git diff --cached` |
| 51 | * Untracked (new files not yet staged): enumerate with `git ls-files --others --exclude-standard`, then read the full content of each file as the review input. |
| 52 | |
| 53 | ## Selected Code |
| 54 | |
| 55 | Use the provided code as the review input; no git diff is needed. Apply all loaded skills or review logic to the selected code. Skip artifact persistence since there is no branch context. |
| 56 | |
| 57 | ## Specific Commit |
| 58 | |
| 59 | ```bash |
| 60 | git diff <commit>^..<commit> |
| 61 | ``` |
| 62 | |
| 63 | ## Scope Rules |
| 64 | |
| 65 | * Do not enumerate, list, or read source files before obtaining the diff or review input. |
| 66 | * Only lines present in the diff (added or modified lines) are in scope for findings. |
| 67 | * For selected code reviews (no diff context), all provided code lines are in scope. |
| 68 | * Read full file contents only for contextual understanding of diff lines, never as a source of findings. |
| 69 | * Pre-existing issues in unchanged code go in the **Out-of-scope Observations** table, clearly labelled and excluded from the verdict. |
| 70 | |
| 71 | ## Large Diff Handling |
| 72 | |
| 73 | Use the `timeout` parameter on terminal commands to prevent hanging on large repositories. |
| 74 | |
| 75 | | Changed Files | Strategy | |
| 76 | |---------------|----------------------------------------------------------------| |
| 77 | | Fewer than 20 | Analyze all files with full diffs. | |
| 78 | | 20 to 50 | Group files by directory and analyze each group. | |
| 79 | | More than 50 | Progressive batched analysis, processing 5-10 files at a time. | |
| 80 | |
| 81 | When a diff exceeds 2000 lines of combined changes or 500 lines in a single file, review the most recent commits individually using `git log --oneline` and `git show --stat`. |
| 82 | |
| 83 | ## Non-Source Artifact Skip List |
| 84 | |
| 85 | Skip these artifacts when computing and analyzing diffs: |
| 86 | |
| 87 | * Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| 88 | * Minified bundles: `.min.js`, `.min.css` |
| 89 | * Source maps: `.map` |
| 90 | * Binaries |
| 91 | * Build output directories: `/bin/`, `/obj/`, `/node_modules/`, `/dist/`, `/out/`, `/coverage/` |
| 92 | |
| 93 | ### Fallback (pr-reference skill unavailable) |
| 94 | |
| 95 | If the pr-reference skill scripts are not found or fail, compute the diff manually: |
| 96 | |
| 97 | 1. Resolve the merge-base: `git merge-base origin/<default-branch> HEAD` |
| 98 | 2. Generate the diff: `git diff <merge-base>...HEAD` |
| 99 | 3. List changed files: `git diff <merge-base>...HEAD --name-only` |
| 100 | 4. For uncommitted changes, supplement with `git diff HEAD`, `git diff --cached`, and `git ls-files --others --exclude-standard` |
| 101 | |
| 102 | Apply the Non-Source Artifact Skip List and Large Diff Handling rules to the manual output. |
| 103 | |
| 104 | --- |
| 105 | |
| 106 | Brought to you by microsoft/hve-core |
| 107 | |