azdo-cli 0.24.0-feature-059-delete-item.906 → 0.24.0-feature-060-pr-comment-anchor.910

package/dist/index.js

@@ -48,7 +48,7 @@ import {
 } from "./chunk-DNOOZIXA.js";
 
 // src/program.ts
-import { Command as Command21 } from "commander";
+import { Command as Command20 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -967,25 +967,6 @@ async function applyWorkItemPatch(context, id, cred, operations) {
   });
   return readWriteResponse(response, "UPDATE_REJECTED");
 }
-async function deleteWorkItem(context, id, cred, permanent = false) {
-  const url = new URL(
-    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
-  );
-  if (permanent) url.searchParams.set("destroy", "true");
-  url.searchParams.set("api-version", "7.1");
-  const response = await fetchWithErrors(url.toString(), {
-    method: "DELETE",
-    headers: authHeaders(cred)
-  });
-  if (response.status === 400) {
-    const serverMessage = await readResponseMessage(response) ?? "Unknown error";
-    throw new Error(`BAD_REQUEST: ${serverMessage}`);
-  }
-  if (!response.ok) {
-    throw httpError(response);
-  }
-  return { id, permanent };
-}
 async function downloadAttachment(url, cred) {
   const response = await fetchWithErrors(url, { headers: authHeaders(cred) });
   if (!response.ok) {
@@ -4315,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`
   );
@@ -4326,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: {
@@ -4337,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`
@@ -4660,6 +4681,36 @@ 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: iterationId, secondComparingIteration: iterationId }
+  };
+  if (changeTrackingId !== void 0) {
+    context.changeTrackingId = changeTrackingId;
+  }
+  return context;
+}
+function findChangeTrackingId(changes, filePath, side) {
+  const byPath = (change) => change.item?.path === filePath;
+  const match = side === "left" ? changes.find((change) => change.originalPath === filePath) ?? changes.find(byPath) : changes.find(byPath);
+  return match?.changeTrackingId;
+}
+
 // src/commands/pr.ts
 function parsePositivePrNumber(raw) {
   if (!/^\d+$/.test(raw)) {
@@ -5813,6 +5864,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 {
@@ -5820,16 +5995,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) => {
@@ -5839,26 +6011,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(
@@ -5867,24 +6026,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) {
@@ -5896,18 +6060,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) {
@@ -6197,13 +6364,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;
@@ -8023,57 +8192,8 @@ function createDeleteAttachmentCommand() {
   return command;
 }
 
-// src/commands/delete-item.ts
-import { Command as Command19 } from "commander";
-function createDeleteItemCommand() {
-  const command = new Command19("delete-item");
-  command.description("Delete an Azure DevOps work item (moves it to the Recycle Bin unless --permanent)").argument("<id>", "work item ID").option("--permanent", "destroy the work item permanently instead of moving it to the Recycle Bin").option("-y, --yes", "skip the interactive confirmation prompt").option("--json", "output { id, permanent, deleted }").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(
-    async (idStr, options) => {
-      const id = parseWorkItemId(idStr);
-      validateOrgProjectPair(options);
-      const permanent = options.permanent === true;
-      let context;
-      try {
-        context = resolveContext(options);
-        const credential = await requireAuthCredential(context.org);
-        let confirmed = options.yes === true;
-        if (!confirmed) {
-          if (!process.stdin.isTTY) {
-            process.stderr.write(
-              "Error: confirmation required. Re-run with --yes to skip the prompt in a non-interactive shell.\n"
-            );
-            process.exitCode = 1;
-            return;
-          }
-          const question = permanent ? `Permanently delete work item ${id}? This cannot be undone. [y/N] ` : `Delete work item ${id} (moves it to the Recycle Bin)? [y/N] `;
-          confirmed = await promptYesNo(question);
-        }
-        if (!confirmed) {
-          process.stderr.write("Aborted: work item not deleted.\n");
-          process.exitCode = 1;
-          return;
-        }
-        await deleteWorkItem(context, id, credential, permanent);
-        if (options.json) {
-          process.stdout.write(`${JSON.stringify({ id, permanent, deleted: true }, null, 2)}
-`);
-        } else {
-          process.stdout.write(
-            permanent ? `Permanently deleted work item ${id}
-` : `Deleted work item ${id}
-`
-          );
-        }
-      } catch (err) {
-        handleCommandError(err, id, context, "write");
-      }
-    }
-  );
-  return command;
-}
-
 // src/commands/relations.ts
-import { Command as Command20 } from "commander";
+import { Command as Command19 } from "commander";
 
 // src/services/relations-client.ts
 var API_VERSION2 = "7.1";
@@ -8290,7 +8410,7 @@ function parsePositiveInt(value, label) {
   return n;
 }
 function createRelationsCommand() {
-  const relations = new Command20("relations").description("Manage work item relations");
+  const relations = new Command19("relations").description("Manage work item relations");
   addCommonOptions(
     relations.command("types").description("List all available work item relation types")
   ).action(async (opts) => {
@@ -8485,7 +8605,7 @@ async function getUpdateNotice(opts) {
 
 // src/program.ts
 function createProgram() {
-  const program2 = new Command21();
+  const program2 = new Command20();
   program2.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
   program2.option("--no-update-check", "Skip the check for a newer published version");
   program2.option("--trace <filepath>", "Append redacted HTTP request/response trace to a file (owner-read-only permissions)");
@@ -8507,7 +8627,6 @@ function createProgram() {
   program2.addCommand(createDownloadAttachmentCommand());
   program2.addCommand(createAddAttachmentCommand());
   program2.addCommand(createDeleteAttachmentCommand());
-  program2.addCommand(createDeleteItemCommand());
   program2.addCommand(createRelationsCommand());
   program2.showHelpAfterError();
   program2.hook("preAction", () => {

package/package.json

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