azdo-cli 0.24.0-feature-059-delete-work-items.905 → 0.24.0-feature-060-pr-comment-anchor.908

package/dist/index.js

@@ -4296,7 +4296,7 @@ async function getPullRequestThread(context, repo, cred, prId, threadId) {
   const data = await readJsonResponse(response);
   return toActiveCommentThread(data);
 }
-async function createPullRequestThread(context, repo, cred, prId, content, status2) {
+async function createPullRequestThread(context, repo, cred, prId, content, status2, anchor) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads`
   );
@@ -4307,6 +4307,10 @@ async function createPullRequestThread(context, repo, cred, prId, content, statu
   if (status2 !== void 0) {
     payload.status = status2;
   }
+  if (anchor !== void 0) {
+    payload.threadContext = anchor.threadContext;
+    payload.pullRequestThreadContext = anchor.pullRequestThreadContext;
+  }
   const response = await fetchWithErrors(url.toString(), {
     method: "POST",
     headers: {
@@ -4318,6 +4322,42 @@ async function createPullRequestThread(context, repo, cred, prId, content, statu
   const data = await readJsonResponse(response);
   return toActiveCommentThread(data);
 }
+function buildIterationsUrl(context, repo, prId, suffix = "") {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/iterations${suffix}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  return url;
+}
+async function getLatestPullRequestIterationId(context, repo, cred, prId) {
+  const url = buildIterationsUrl(context, repo, prId);
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
+  const data = await readJsonResponse(response);
+  const ids = (data.value ?? []).map((iteration) => iteration.id);
+  if (ids.length === 0) {
+    throw new Error(`Pull request #${prId} has no iterations.`);
+  }
+  return Math.max(...ids);
+}
+async function getPullRequestIterationChanges(context, repo, cred, prId, iterationId) {
+  const changes = [];
+  let skip = 0;
+  for (; ; ) {
+    const url = buildIterationsUrl(context, repo, prId, `/${iterationId}/changes`);
+    url.searchParams.set("$top", "2000");
+    if (skip > 0) {
+      url.searchParams.set("$skip", String(skip));
+    }
+    const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
+    const page = await readJsonResponse(response);
+    changes.push(...page.changeEntries ?? []);
+    const next = page.nextSkip ?? 0;
+    if (next <= skip) {
+      return changes;
+    }
+    skip = next;
+  }
+}
 function buildThreadCommentUrl(context, repo, prId, threadId) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads/${threadId}/comments`
@@ -4641,6 +4681,35 @@ async function resolvePullRequestTemplate(context, repo, cred, defaultBranch, ta
   return firstMatchingTemplate(context, repo, cred, defaultBranch, defaultTemplateCandidates(), "default");
 }
 
+// src/services/thread-anchor.ts
+var LINE_END_OFFSET = 1e3;
+function normalizeThreadFilePath(raw) {
+  let path5 = raw.trim().replaceAll("\\", "/");
+  while (path5.startsWith("./")) {
+    path5 = path5.slice(2);
+  }
+  path5 = path5.replace(/^\/+/, "");
+  return path5 === "" ? null : `/${path5}`;
+}
+function buildThreadAnchorContext(filePath, line, endLine, side) {
+  const start = { line, offset: 1 };
+  const end = { line: endLine, offset: LINE_END_OFFSET };
+  return side === "right" ? { filePath, rightFileStart: start, rightFileEnd: end } : { filePath, leftFileStart: start, leftFileEnd: end };
+}
+function buildPullRequestThreadContext(iterationId, changeTrackingId) {
+  const context = {
+    iterationContext: { firstComparingIteration: 1, secondComparingIteration: iterationId }
+  };
+  if (changeTrackingId !== void 0) {
+    context.changeTrackingId = changeTrackingId;
+  }
+  return context;
+}
+function findChangeTrackingId(changes, filePath, side) {
+  const match = changes.find((change) => change.item?.path === filePath) ?? (side === "left" ? changes.find((change) => change.originalPath === filePath) : void 0);
+  return match?.changeTrackingId;
+}
+
 // src/commands/pr.ts
 function parsePositivePrNumber(raw) {
   if (!/^\d+$/.test(raw)) {
@@ -5794,6 +5863,130 @@ var CREATABLE_THREAD_STATUSES = [
   "byDesign",
   "pending"
 ];
+var THREAD_ANCHOR_SIDES = ["right", "left"];
+function parseCommentAddStatus(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const match = CREATABLE_THREAD_STATUSES.find((candidate) => candidate === raw);
+  if (match === void 0) {
+    writeError(`Invalid --status "${raw}"; expected one of ${CREATABLE_THREAD_STATUSES.join(", ")}.`);
+    return null;
+  }
+  return match;
+}
+function parseLineOption(flag, raw) {
+  const value = parsePositivePrNumber(raw);
+  if (value === null) {
+    writeError(`Invalid ${flag} "${raw}"; expected a positive integer (1-based line number).`);
+  }
+  return value;
+}
+function parseCommentAnchorOptions(options) {
+  if (options.filePath === void 0) {
+    const stray = [
+      ["--line", options.line],
+      ["--end-line", options.endLine],
+      ["--side", options.side],
+      ["--allow-unchanged-file", options.allowUnchangedFile]
+    ].find(([, value]) => value !== void 0);
+    if (stray !== void 0) {
+      writeError(`${stray[0]} requires --file-path.`);
+      return null;
+    }
+    return void 0;
+  }
+  if (options.line === void 0) {
+    writeError("--file-path requires --line.");
+    return null;
+  }
+  const filePath = normalizeThreadFilePath(options.filePath);
+  if (filePath === null) {
+    writeError(`Invalid --file-path "${options.filePath}"; expected a repository file path.`);
+    return null;
+  }
+  const line = parseLineOption("--line", options.line);
+  if (line === null) {
+    return null;
+  }
+  const endLine = options.endLine === void 0 ? line : parseLineOption("--end-line", options.endLine);
+  if (endLine === null) {
+    return null;
+  }
+  if (endLine < line) {
+    writeError(`--end-line (${endLine}) must not be less than --line (${line}).`);
+    return null;
+  }
+  const side = THREAD_ANCHOR_SIDES.find((candidate) => candidate === (options.side ?? "right"));
+  if (side === void 0) {
+    writeError(`Invalid --side "${options.side}"; expected ${THREAD_ANCHOR_SIDES.join(" or ")}.`);
+    return null;
+  }
+  return { filePath, line, endLine, side, allowUnchangedFile: options.allowUnchangedFile === true };
+}
+async function resolveCommentAnchor(target, request) {
+  const prId = target.pullRequest.id;
+  const iterationId = await getLatestPullRequestIterationId(target.context, target.repo, target.pat, prId);
+  const changes = await getPullRequestIterationChanges(target.context, target.repo, target.pat, prId, iterationId);
+  const changeTrackingId = findChangeTrackingId(changes, request.filePath, request.side);
+  if (changeTrackingId === void 0 && !request.allowUnchangedFile) {
+    writeError(
+      `${request.filePath} is not among the files changed by pull request #${prId} (iteration ${iterationId}). Check the path, or pass --allow-unchanged-file to post the comment anyway.`,
+      3
+    );
+    return null;
+  }
+  return {
+    request,
+    iterationId,
+    changeTrackingId,
+    threadContext: buildThreadAnchorContext(request.filePath, request.line, request.endLine, request.side),
+    pullRequestThreadContext: buildPullRequestThreadContext(iterationId, changeTrackingId)
+  };
+}
+function describeCommentAnchor(anchor) {
+  const { filePath, line, endLine, side } = anchor.request;
+  const lines = line === endLine ? `line ${line}` : `lines ${line}-${endLine}`;
+  const tracking = anchor.changeTrackingId === void 0 ? "no changeTrackingId" : `changeTrackingId ${anchor.changeTrackingId}`;
+  return ` at ${filePath} ${lines} (${side} side, iteration ${anchor.iterationId}, ${tracking})`;
+}
+function warnIfUntracked(anchor) {
+  if (anchor !== void 0 && anchor.changeTrackingId === void 0) {
+    process.stderr.write(
+      `Note: ${anchor.request.filePath} is not among the pull request's changed files, so the thread is posted without a changeTrackingId and will not follow the line across later pushes.
+`
+    );
+  }
+}
+function withAnchorFields(result, anchor) {
+  if (anchor === void 0) {
+    return result;
+  }
+  return {
+    ...result,
+    threadContext: anchor.threadContext,
+    pullRequestThreadContext: anchor.pullRequestThreadContext,
+    changeTracked: anchor.changeTrackingId !== void 0
+  };
+}
+function writeCommentAddDryRun(prId, body, status2, anchor, json) {
+  if (json) {
+    const dryResult = withAnchorFields(
+      { pullRequestId: prId, threadId: null, commentId: null, status: status2 ?? null, content: body, dryRun: true },
+      anchor
+    );
+    process.stdout.write(`${JSON.stringify(dryResult, null, 2)}
+`);
+    return;
+  }
+  const statusSuffix = status2 === void 0 ? "" : ` with status ${status2}`;
+  const anchorSuffix = anchor === void 0 ? "" : describeCommentAnchor(anchor);
+  process.stdout.write(
+    `Dry run: would post a new comment thread${statusSuffix} on pull request #${prId}${anchorSuffix} (${body.length} chars).
+${body}
+`
+  );
+}
 async function runCommentAdd(text, options) {
   let context;
   try {
@@ -5801,16 +5994,13 @@ async function runCommentAdd(text, options) {
     if (body === null) {
       return;
     }
-    let status2;
-    if (options.status !== void 0) {
-      const match = CREATABLE_THREAD_STATUSES.find((candidate) => candidate === options.status);
-      if (match === void 0) {
-        writeError(
-          `Invalid --status "${options.status}"; expected one of ${CREATABLE_THREAD_STATUSES.join(", ")}.`
-        );
-        return;
-      }
-      status2 = match;
+    const status2 = parseCommentAddStatus(options.status);
+    if (status2 === null) {
+      return;
+    }
+    const anchorRequest = parseCommentAnchorOptions(options);
+    if (anchorRequest === null) {
+      return;
     }
     const target = await resolvePullRequestTarget(options, {
       onContextResolved: (resolved) => {
@@ -5820,26 +6010,13 @@ async function runCommentAdd(text, options) {
     if (target === null) {
       return;
     }
+    const anchor = anchorRequest === void 0 ? void 0 : await resolveCommentAnchor(target, anchorRequest);
+    if (anchor === null) {
+      return;
+    }
+    warnIfUntracked(anchor);
     if (options.dryRun === true) {
-      const dryResult = {
-        pullRequestId: target.pullRequest.id,
-        threadId: null,
-        commentId: null,
-        status: status2 ?? null,
-        content: body,
-        dryRun: true
-      };
-      if (options.json) {
-        process.stdout.write(`${JSON.stringify(dryResult, null, 2)}
-`);
-        return;
-      }
-      const statusSuffix = status2 === void 0 ? "" : ` with status ${status2}`;
-      process.stdout.write(
-        `Dry run: would post a new comment thread${statusSuffix} on pull request #${target.pullRequest.id} (${body.length} chars).
-${body}
-`
-      );
+      writeCommentAddDryRun(target.pullRequest.id, body, status2, anchor, options.json);
       return;
     }
     const thread = await createPullRequestThread(
@@ -5848,24 +6025,29 @@ ${body}
       target.pat,
       target.pullRequest.id,
       body,
-      status2
+      status2,
+      ...anchor === void 0 ? [] : [{ threadContext: anchor.threadContext, pullRequestThreadContext: anchor.pullRequestThreadContext }]
     );
     const created = thread.comments[0];
-    const result = {
-      pullRequestId: target.pullRequest.id,
-      threadId: thread.id,
-      commentId: created?.id ?? null,
-      status: thread.status,
-      content: created?.content ?? body,
-      dryRun: false
-    };
+    const result = withAnchorFields(
+      {
+        pullRequestId: target.pullRequest.id,
+        threadId: thread.id,
+        commentId: created?.id ?? null,
+        status: thread.status,
+        content: created?.content ?? body,
+        dryRun: false
+      },
+      anchor
+    );
     if (options.json) {
       process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       return;
     }
+    const anchorSuffix = anchor === void 0 ? "" : describeCommentAnchor(anchor);
     process.stdout.write(
-      `Comment posted to pull request #${target.pullRequest.id} (thread #${thread.id}).
+      `Comment posted to pull request #${target.pullRequest.id} (thread #${thread.id})${anchorSuffix}.
 `
     );
   } catch (err) {
@@ -5877,18 +6059,21 @@ function buildCommentAddCommand(name, description) {
   withCommonPrOptions(configureUnwrappedHelp(command)).description(description).argument("[text]", "body of the new comment; omit when using --file").option("--file <path>", "read the comment body from a UTF-8 file instead of the inline argument").option(
     "--status <status>",
     `thread status (${CREATABLE_THREAD_STATUSES.join(" | ")}); omit for a plain, non-resolvable comment`
+  ).option("--file-path <path>", "anchor the thread to this repository file (Files tab); requires --line").option("--line <n>", "first line of the anchored range (1-based)").option("--end-line <n>", "last line of the anchored range (default: --line)").option("--side <side>", "right (new version, default) or left (old version, for deleted lines)").option(
+    "--allow-unchanged-file",
+    "post even when --file-path is not among the pull request's changed files (the thread will not follow the line across pushes)"
   ).option("--dry-run", "resolve the target pull request and print what would be posted, without writing anything").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (text, _options, command2) => {
     await runCommentAdd(text, mergedPrOptions(command2));
   });
   return command;
 }
 function createPrCommentsAddCommand() {
-  return buildCommentAddCommand("add", "Post a new comment thread on the pull request overview");
+  return buildCommentAddCommand("add", "Post a new comment thread on the pull request overview, or on a file and line");
 }
 function createPrCommentAddCommand() {
   return buildCommentAddCommand(
     "comment-add",
-    'Post a new comment thread on the pull request overview (alias of "azdo pr comments add")'
+    'Post a new comment thread on the pull request overview, or on a file and line (alias of "azdo pr comments add")'
   );
 }
 function parseExplicitCommentId(options) {
@@ -6178,13 +6363,15 @@ async function attachWorkItemIds(context, repo, cred, pullRequests) {
   const result = new Array(pullRequests.length);
   let next = 0;
   const worker = async () => {
-    while (next < pullRequests.length) {
-      const index = next;
-      next += 1;
-      const pullRequest = pullRequests[index];
-      const workItemIds = await getPullRequestWorkItemIds(context, repo, cred, pullRequest.id);
-      result[index] = { ...pullRequest, workItemIds };
+    if (next >= pullRequests.length) {
+      return;
     }
+    const index = next;
+    next += 1;
+    const pullRequest = pullRequests[index];
+    const workItemIds = await getPullRequestWorkItemIds(context, repo, cred, pullRequest.id);
+    result[index] = { ...pullRequest, workItemIds };
+    await worker();
   };
   await Promise.all(Array.from({ length: Math.min(WORK_ITEM_LOOKUP_CONCURRENCY, pullRequests.length) }, worker));
   return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.24.0-feature-059-delete-work-items.905",
+  "version": "0.24.0-feature-060-pr-comment-anchor.908",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {