@@ -13,11 +13,15 @@ import { getErrorMessage, GitHubVariant, satisfiesGHESVersion } from "../util";
1313 * This interface is an abbreviated version of the file diff object returned by
1414 * the GitHub API.
1515 */
16- interface FileDiff {
16+ export interface FileDiff {
17+ /** The name of the file that has changed. */
1718 filename : string ;
19+ /** The number of changes. */
1820 changes : number ;
19- // A patch may be absent if the file is binary, if the file diff is too large,
20- // or if the file is unchanged.
21+ /**
22+ * The diff, if available. It may be absent if the file is binary, if the file diff is too large,
23+ * or if the file is unchanged.
24+ */
2125 patch ?: string | undefined ;
2226}
2327
@@ -93,13 +97,23 @@ export async function prepareDiffInformedAnalysis(
9397 }
9498}
9599
100+ /** Describes a changed line range in a file. */
96101export interface DiffThunkRange {
97102 /** Relative path from the repository root, using forward slashes as separators. */
98103 path : string ;
104+ /** The starting line of the change (1-based and inclusive). */
99105 startLine : number ;
106+ /** The last line of the change (1-based and inclusive). */
100107 endLine : number ;
101108}
102109
110+ /**
111+ * Writes an array of {@link DiffThunkRange} objects to the file given by
112+ * {@link actionsUtil.getDiffRangesJsonFilePath}.
113+ *
114+ * @param logger The logger to use.
115+ * @param ranges The changed line ranges to write.
116+ */
103117export function writeDiffRangesJsonFile (
104118 logger : Logger ,
105119 ranges : DiffThunkRange [ ] ,
@@ -112,6 +126,13 @@ export function writeDiffRangesJsonFile(
112126 ) ;
113127}
114128
129+ /**
130+ * Reads an array of {@link DiffThunkRange} objects from the file given by
131+ * {@link actionsUtil.getDiffRangesJsonFilePath}.
132+ *
133+ * @param logger The logger to use.
134+ * @returns The array of {@link DiffThunkRange} objects or `undefined` if the file couldn't be read.
135+ */
115136export function readDiffRangesJsonFile (
116137 logger : Logger ,
117138) : DiffThunkRange [ ] | undefined {
@@ -138,12 +159,12 @@ export function readDiffRangesJsonFile(
138159 * Return the file line ranges that were added or modified in the pull request.
139160 *
140161 * @param branches The base and head branches of the pull request.
141- * @param logger
142- * @returns An array of tuples, where each tuple contains the relative path of a
143- * file (relative to the repository root, as returned by the GitHub compare API),
144- * the start line and the end line (both 1-based and inclusive) of an
145- * added or modified range in that file. Returns `undefined` if the action was
146- * not triggered by a pull request or if there was an error .
162+ * @param logger The logger to use.
163+ *
164+ * @returns
165+ * An array of { @link DiffThunkRange} objects, where each describes a line range in a file
166+ * that was changed in the pull request described by { @link branches} or `undefined` if
167+ * we were unable to compute them .
147168 */
148169export async function getPullRequestEditedDiffRanges (
149170 branches : PullRequestBranches ,
@@ -182,7 +203,8 @@ export async function getPullRequestEditedDiffRanges(
182203 *
183204 * @param branches The base and head branches of the pull request, as returned
184205 * by `getDiffInformedAnalysisBranches`.
185- * @param logger
206+ * @param logger The logger to use.
207+ *
186208 * @returns `true` if the diff ranges were successfully computed and persisted,
187209 * otherwise `false`.
188210 */
@@ -203,6 +225,19 @@ export async function computeAndPersistDiffRanges(
203225 return true ;
204226}
205227
228+ /**
229+ * Fetch an array of {@link FileDiff} objects using the GitHub API describing the changed files
230+ * in the pull request with the base and head refs given by {@link branches}.
231+ *
232+ * @param branches The pull request branch refs.
233+ * @param logger The logger to use.
234+ *
235+ * @throws Non-HTTP errors that occur while fetching the file diffs.
236+ *
237+ * @returns
238+ * An array of {@link FileDiff} objects describing the changed files in the PR, or
239+ * `undefined` if we couldn't obtain the changed files from the API.
240+ */
206241async function getFileDiffsWithBasehead (
207242 branches : PullRequestBranches ,
208243 logger : Logger ,
@@ -243,6 +278,16 @@ async function getFileDiffsWithBasehead(
243278 }
244279}
245280
281+ /**
282+ * Extracts an array of {@link DiffThunkRange} objects from {@link fileDiff}.
283+ *
284+ * @param fileDiff The {@link FileDiff} object describing changes to a particular file.
285+ * @param logger The logger to use.
286+ *
287+ * @returns
288+ * The {@link DiffThunkRange} objects extracted from {@link fileDiff},
289+ * or `undefined` if there are none that could be extracted.
290+ */
246291function getDiffRanges (
247292 fileDiff : FileDiff ,
248293 logger : Logger ,
0 commit comments