dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-github-review/lib/normalize.js

@@ -0,0 +1,662 @@
+/**
+ * dsh-github-review — pure parsing, normalization and redaction helpers.
+ *
+ * Nothing here spawns processes, touches the filesystem or uses the network:
+ * JSON/text produced by the `gh` CLI goes in, compact review objects come out.
+ * That keeps every parsing rule unit-testable without a GitHub account, and
+ * keeps secrets out of anything this plugin prints.
+ */
+
+const CHECK_BUCKETS = new Set(["pass", "fail", "pending", "skipping", "cancel"]);
+
+/** Hard limits so one giant PR cannot flood the model context. */
+export const LIMITS = Object.freeze({
+  bodyChars: 16_000,
+  commentChars: 300,
+  files: 60,
+  commits: 40,
+  checks: 200,
+  inlineComments: 100,
+  threads: 40,
+  conversation: 40,
+  diffBytes: 200 * 1024,
+  minDiffBytes: 4 * 1024,
+  maxDiffBytes: 2 * 1024 * 1024,
+  maxCommentChars: 60_000,
+});
+
+/** Environment variables whose values must never be echoed back. */
+const SECRET_ENV_NAMES = ["GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"];
+
+const BUCKET_BY_STATE = new Map([
+  ["SUCCESS", "pass"],
+  ["PASS", "pass"],
+  ["PASSED", "pass"],
+  ["FAILURE", "fail"],
+  ["FAIL", "fail"],
+  ["FAILED", "fail"],
+  ["ERROR", "fail"],
+  ["TIMED_OUT", "fail"],
+  ["ACTION_REQUIRED", "fail"],
+  ["STARTUP_FAILURE", "fail"],
+  ["NEUTRAL", "skipping"],
+  ["SKIPPED", "skipping"],
+  ["SKIP", "skipping"],
+  ["CANCELLED", "cancel"],
+  ["CANCELED", "cancel"],
+  ["PENDING", "pending"],
+  ["QUEUED", "pending"],
+  ["IN_PROGRESS", "pending"],
+  ["WAITING", "pending"],
+  ["REQUESTED", "pending"],
+  ["EXPECTED", "pending"],
+]);
+
+const REDACTION_RULES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, "[REDACTED:PRIVATE_KEY]"],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, "[REDACTED:JWT]"],
+  [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED:GITHUB_TOKEN]"],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/gu, "[REDACTED:GITHUB_TOKEN]"],
+  [/\b(?:sk|rk)-[A-Za-z0-9_-]{16,}\b/gu, "[REDACTED:SERVICE_KEY]"],
+  [/\bglpat-[A-Za-z0-9_-]{20,}\b/gu, "[REDACTED:GITLAB_TOKEN]"],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gu, "[REDACTED:SLACK_TOKEN]"],
+  [/\bAKIA[0-9A-Z]{16}\b/gu, "[REDACTED:AWS_KEY]"],
+  [/\bAIza[0-9A-Za-z_-]{30,}\b/gu, "[REDACTED:GOOGLE_KEY]"],
+  [/\bnpm_[A-Za-z0-9]{36}\b/gu, "[REDACTED:NPM_TOKEN]"],
+  [/\b(?:Authorization|Proxy-Authorization)\s*:\s*(?:Bearer|Basic|Token)\s+[^\s]+/giu, "Authorization: [REDACTED]"],
+  [/\b(?:Set-)?Cookie\s*:\s*[^\r\n]+/giu, "[REDACTED:COOKIE]"],
+  [/\b([a-z][a-z0-9+.-]*:\/\/)[^:@/\s]+:[^@/\s]+@/giu, "$1[REDACTED]@"],
+  [
+    /(^|\n)(\s*[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|API[_-]?KEY|PRIVATE[_-]?KEY|ACCESS[_-]?KEY)[A-Z0-9_]*\s*[:=]\s*)[^\s"',;\r\n]+/gu,
+    "$1$2[REDACTED]",
+  ],
+];
+
+/* ------------------------------------------------------------------ */
+/* Small scalar helpers                                                */
+/* ------------------------------------------------------------------ */
+
+function asString(value) {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "";
+  return String(value);
+}
+
+function asCount(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;
+}
+
+function asPositiveInt(value) {
+  const number = Number(value);
+  return Number.isSafeInteger(number) && number > 0 ? number : undefined;
+}
+
+/** Strip ANSI colour/OSC sequences from captured terminal output. */
+export function stripAnsi(value) {
+  return asString(value)
+    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/gu, "")
+    .replace(/\u001B\[[0-9;?]*[A-Za-z]/gu, "");
+}
+
+/** One-line excerpt: collapse whitespace, cut on a character boundary. */
+export function snippet(value, max = LIMITS.commentChars) {
+  const text = asString(value).replace(/\s+/gu, " ").trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+
+export function formatBytes(bytes) {
+  const value = Number(bytes);
+  if (!Number.isFinite(value) || value < 0) return "0 B";
+  if (value < 1024) return `${Math.floor(value)} B`;
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KiB`;
+  return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
+export function byteLength(text) {
+  return Buffer.byteLength(asString(text), "utf8");
+}
+
+/** Clamp a user-supplied diff byte budget. */
+export function clampDiffBytes(value) {
+  const number = Number(value);
+  const fallback = LIMITS.diffBytes;
+  if (!Number.isFinite(number) || number <= 0) return fallback;
+  return Math.max(LIMITS.minDiffBytes, Math.min(LIMITS.maxDiffBytes, Math.floor(number)));
+}
+
+export function truncateChars(value, max) {
+  const text = asString(value);
+  const limit = Number.isFinite(Number(max)) && Number(max) > 0 ? Math.floor(Number(max)) : LIMITS.bodyChars;
+  if (text.length <= limit) return { text, truncated: false, chars: text.length };
+  return { text: `${text.slice(0, limit)}…`, truncated: true, chars: text.length };
+}
+
+function charIndexForBytes(text, maxBytes) {
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(text.slice(0, mid), "utf8") <= maxBytes) low = mid;
+    else high = mid - 1;
+  }
+  return low;
+}
+
+/**
+ * Byte-capped text for a diff. Cuts on a line boundary when possible so the
+ * model never receives half a diff line; always reports the original size.
+ */
+export function truncateBytes(value, maxBytes) {
+  const text = asString(value);
+  const total = Buffer.byteLength(text, "utf8");
+  const limit = Number.isFinite(Number(maxBytes)) && Number(maxBytes) > 0 ? Math.floor(Number(maxBytes)) : LIMITS.diffBytes;
+  if (total <= limit) return { text, truncated: false, bytes: total, shownBytes: total };
+  const index = charIndexForBytes(text, limit);
+  const boundary = text.lastIndexOf("\n", index);
+  const end = boundary > 0 ? boundary : index;
+  const shown = text.slice(0, end);
+  return { text: shown, truncated: true, bytes: total, shownBytes: Buffer.byteLength(shown, "utf8") };
+}
+
+/** Convenience wrapper used by the diff action. */
+export function truncateDiff(patch, maxBytes) {
+  return truncateBytes(patch, clampDiffBytes(maxBytes));
+}
+
+/* ------------------------------------------------------------------ */
+/* Redaction                                                           */
+/* ------------------------------------------------------------------ */
+
+/** Remove token-shaped secrets from text this plugin prints. */
+export function redactSecrets(value) {
+  let text = asString(value);
+  for (const [pattern, replacement] of REDACTION_RULES) text = text.replace(pattern, replacement);
+  return text;
+}
+
+/** Remove values of token environment variables, whatever their shape. */
+export function redactEnvironmentValues(value, env = {}) {
+  let text = asString(value);
+  for (const name of SECRET_ENV_NAMES) {
+    const secret = env?.[name];
+    if (typeof secret !== "string" || secret.length < 8) continue;
+    text = text.split(secret).join("[REDACTED:ENV]");
+  }
+  return text;
+}
+
+/** Full scrub for captured command output before it becomes a tool result. */
+export function scrubOutput(value, env = {}) {
+  return redactEnvironmentValues(redactSecrets(stripAnsi(value)), env);
+}
+
+/* ------------------------------------------------------------------ */
+/* Identifiers                                                         */
+/* ------------------------------------------------------------------ */
+
+/** Positive PR number, or `undefined` for anything ambiguous. */
+export function parsePrNumber(value) {
+  if (typeof value === "number") {
+    return Number.isSafeInteger(value) && value > 0 && value <= 10_000_000 ? value : undefined;
+  }
+  if (typeof value === "string" && /^\s*\d{1,7}\s*$/u.test(value)) {
+    const number = Number(value.trim());
+    return number > 0 ? number : undefined;
+  }
+  return undefined;
+}
+
+const REPO_PART = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/u;
+
+function validRepoPart(part) {
+  return typeof part === "string" && part.length > 0 && part !== "." && part !== ".." && REPO_PART.test(part);
+}
+
+/**
+ * Parse `owner/name` or `host/owner/name` (GHES). Returns `undefined` for
+ * anything that is not a strict repository spec, so it can never reach `gh`
+ * as an option or a path fragment.
+ */
+export function parseRepoSpec(value) {
+  const text = asString(value).trim();
+  if (text.length === 0 || text.length > 300 || /\s/u.test(text)) return undefined;
+  const parts = text.split("/");
+  if (parts.length !== 2 && parts.length !== 3) return undefined;
+  const owner = parts.at(-2);
+  const name = parts.at(-1);
+  if (!validRepoPart(owner) || !validRepoPart(name)) return undefined;
+  const host = parts.length === 3 ? parts[0] : "github.com";
+  if (parts.length === 3 && (!validRepoPart(host.replace(/:\d+$/u, "")) || !/^[A-Za-z0-9.-]+(?::\d+)?$/u.test(host))) return undefined;
+  return {
+    host,
+    owner,
+    name,
+    slug: `${owner}/${name}`,
+    webUrl: `https://${host}/${owner}/${name}`,
+  };
+}
+
+/** Argument for `gh --repo`: `owner/name` on github.com, `host/owner/name` elsewhere. */
+export function repoArgument(spec) {
+  if (!spec) return undefined;
+  return spec.host === "github.com" ? spec.slug : `${spec.host}/${spec.slug}`;
+}
+
+/**
+ * Parse a git remote URL into a repository spec. Handles https, ssh, git://,
+ * scp-like `git@host:owner/name.git`, and returns `undefined` for local paths
+ * or anything unparseable — never guesses.
+ */
+export function parseGitRemoteUrl(value) {
+  const raw = asString(value).trim();
+  if (raw.length === 0) return undefined;
+  if (/^[A-Za-z]:[\\/]/u.test(raw) || raw.startsWith("/") || raw.startsWith("./") || raw.startsWith("../") || /^file:/iu.test(raw)) {
+    return undefined;
+  }
+  const scpLike = /^(?:[^@\s/]+@)?([A-Za-z0-9.-]+\.[A-Za-z]{2,}):([^/\s]+)\/([^/\s]+?)(?:\.git)?$/u.exec(raw);
+  if (scpLike) {
+    const [, host, owner, name] = scpLike;
+    return parseRepoSpec(`${host}/${owner}/${name}`);
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return undefined;
+  }
+  if (!["http:", "https:", "ssh:", "git:"].includes(url.protocol) || url.hostname.length === 0) return undefined;
+  const segments = url.pathname.split("/").filter((segment) => segment.length > 0);
+  if (segments.length < 2) return undefined;
+  const name = segments.at(-1).replace(/\.git$/u, "");
+  return parseRepoSpec(`${url.hostname}/${segments.at(-2)}/${name}`);
+}
+
+/** Extract host/owner/name/number from a pull-request URL. */
+export function parseRepoFromPrUrl(value) {
+  const match = /^https?:\/\/([^/\s]+)\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#]|$)/iu.exec(asString(value).trim());
+  if (!match) return undefined;
+  const spec = parseRepoSpec(`${match[1]}/${match[2]}/${match[3]}`);
+  if (!spec) return undefined;
+  const number = parsePrNumber(match[4]);
+  if (!number) return undefined;
+  return { ...spec, number };
+}
+
+/* ------------------------------------------------------------------ */
+/* gh auth status                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Parse `gh auth status` (both the 2.x multi-account layout and the older
+ * `as <login>` layout). Token values are deliberately not extracted at all.
+ */
+export function parseGhAuthStatus(value) {
+  const lines = stripAnsi(value).split(/\r?\n/u);
+  const accounts = [];
+  const failedHosts = [];
+  let host = "";
+  let notLoggedIn = false;
+  let current;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    if (/not logged in(?: to| into)? any github hosts/iu.test(line) || /You are not logged into any GitHub hosts/iu.test(line)) {
+      notLoggedIn = true;
+      continue;
+    }
+    const hostOnly = /^([A-Za-z0-9.-]+\.[A-Za-z]{2,}(?::\d+)?)$/u.exec(line);
+    if (hostOnly && !current) {
+      host = hostOnly[1].toLowerCase();
+      continue;
+    }
+    const loginMatch = /✓\s+Logged in to\s+([^\s]+)\s+(?:account\s+([^\s(]+)|as\s+([^\s(]+))\s*(?:\(([^)]*)\))?/u.exec(line);
+    if (loginMatch) {
+      current = {
+        host: (loginMatch[1] || host).toLowerCase(),
+        login: loginMatch[2] ?? loginMatch[3] ?? "",
+        method: loginMatch[4] ?? "",
+        active: false,
+        scopes: [],
+        protocol: "",
+      };
+      host = current.host;
+      accounts.push(current);
+      continue;
+    }
+    if (!current) {
+      const failed = /^X\s+([^\s:]+)(?::\s*(.*))?$/u.exec(line);
+      if (failed) failedHosts.push((failed[1] || "").toLowerCase());
+      continue;
+    }
+    const activeMatch = /^[-•*]\s*Active account:\s*(true|false)/iu.exec(line);
+    if (activeMatch) {
+      current.active = activeMatch[1].toLowerCase() === "true";
+      continue;
+    }
+    const scopesMatch = /^[-•*]\s*Token scopes:\s*(.+)$/iu.exec(line);
+    if (scopesMatch) {
+      current.scopes = scopesMatch[1]
+        .split(",")
+        .map((scope) => scope.trim().replace(/^['"]|['"]$/gu, ""))
+        .filter(Boolean);
+      continue;
+    }
+    const protocolMatch = /^[-•*]\s*Git operations protocol:\s*(\S+)/iu.exec(line);
+    if (protocolMatch) current.protocol = protocolMatch[1];
+  }
+
+  const active = accounts.find((account) => account.active) ?? accounts[0];
+  return {
+    authenticated: accounts.some((account) => account.login.length > 0),
+    notLoggedIn,
+    host: active?.host ?? host,
+    accounts,
+    active: active ?? null,
+    scopes: active?.scopes ?? [],
+    failedHosts,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Pull request                                                        */
+/* ------------------------------------------------------------------ */
+
+function loginOf(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value.trim();
+  return asString(value.login ?? value.name ?? value.email ?? "").trim();
+}
+
+function normalizeFiles(files) {
+  const list = Array.isArray(files) ? files.filter(Boolean) : [];
+  const items = list.slice(0, LIMITS.files).map((file) => ({
+    path: asString(file.path),
+    additions: asCount(file.additions),
+    deletions: asCount(file.deletions),
+    changeType: asString(file.changeType).toUpperCase(),
+  }));
+  return { total: list.length, items, truncated: list.length > items.length };
+}
+
+function normalizeCommits(commits) {
+  const list = Array.isArray(commits) ? commits.filter(Boolean) : [];
+  const items = list.slice(0, LIMITS.commits).map((commit) => {
+    const oid = asString(commit.oid);
+    const authors = Array.isArray(commit.authors) ? commit.authors : [];
+    return {
+      oid,
+      shortOid: oid.slice(0, 7),
+      messageHeadline: asString(commit.messageHeadline).trim(),
+      author: loginOf(authors[0] ?? commit.author),
+      committedDate: asString(commit.committedDate ?? commit.authoredDate),
+    };
+  });
+  return { total: list.length, items, truncated: list.length > items.length };
+}
+
+function normalizeLabels(labels) {
+  const list = Array.isArray(labels) ? labels.filter(Boolean) : [];
+  return list
+    .slice(0, 20)
+    .map((label) => (typeof label === "string" ? { name: label, color: "" } : { name: asString(label.name), color: asString(label.color) }))
+    .filter((label) => label.name.length > 0);
+}
+
+/** Normalise `gh pr view --json ...` output into the tool's PR shape. */
+export function normalizePullRequest(value) {
+  const json = value !== null && typeof value === "object" ? value : {};
+  const body = truncateChars(json.body, LIMITS.bodyChars);
+  const files = normalizeFiles(json.files);
+  const commits = normalizeCommits(json.commits);
+  return {
+    number: parsePrNumber(json.number),
+    title: asString(json.title).trim(),
+    url: asString(json.url),
+    state: asString(json.state).toUpperCase(),
+    isDraft: json.isDraft === true,
+    author: loginOf(json.author),
+    base: { branch: asString(json.baseRefName), oid: asString(json.baseRefOid) },
+    head: { branch: asString(json.headRefName), oid: asString(json.headRefOid) },
+    body: { ...body, empty: body.text.trim().length === 0 },
+    additions: asCount(json.additions),
+    deletions: asCount(json.deletions),
+    changedFiles: asCount(json.changedFiles) || files.total,
+    files,
+    commits,
+    reviewDecision: asString(json.reviewDecision).toUpperCase(),
+    mergeable: asString(json.mergeable).toUpperCase(),
+    labels: normalizeLabels(json.labels),
+    createdAt: asString(json.createdAt),
+    updatedAt: asString(json.updatedAt),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* CI checks                                                           */
+/* ------------------------------------------------------------------ */
+
+function bucketFromState(value) {
+  return BUCKET_BY_STATE.get(asString(value).toUpperCase());
+}
+
+function normalizeCheckRow(row) {
+  const item = row !== null && typeof row === "object" ? row : {};
+  const workflow = asString(item.workflow);
+  const name = asString(item.name ?? item.context).trim() || (workflow.length > 0 ? workflow : "check");
+  const state = asString(item.state ?? item.conclusion ?? item.status).toUpperCase();
+  const given = asString(item.bucket).toLowerCase();
+  const bucket = CHECK_BUCKETS.has(given) ? given : bucketFromState(item.conclusion) ?? bucketFromState(item.state) ?? bucketFromState(item.status) ?? "unknown";
+  return {
+    name,
+    workflow,
+    bucket,
+    state,
+    description: snippet(item.description, 240),
+    link: asString(item.link ?? item.detailsUrl ?? item.targetUrl),
+    startedAt: asString(item.startedAt),
+    completedAt: asString(item.completedAt),
+  };
+}
+
+/**
+ * Normalise check rows from `gh pr checks --json` or `statusCheckRollup`
+ * (CheckRun / StatusContext nodes). Summaries drive the "failed" headline.
+ */
+export function normalizeChecks(rows) {
+  const list = Array.isArray(rows) ? rows.filter(Boolean) : [];
+  const items = list.slice(0, LIMITS.checks).map(normalizeCheckRow);
+  const summary = { pass: 0, fail: 0, pending: 0, skipping: 0, cancel: 0, unknown: 0 };
+  for (const item of items) summary[item.bucket] += 1;
+  const failed = items.filter((item) => item.bucket === "fail");
+  const pending = items.filter((item) => item.bucket === "pending");
+  return {
+    total: list.length,
+    items,
+    truncated: list.length > items.length,
+    summary,
+    failed,
+    pending,
+  };
+}
+
+function cellsOf(line) {
+  if (line.includes("\t")) return line.split("\t").map((cell) => cell.trim());
+  return line.split(/\s{2,}/u).map((cell) => cell.trim());
+}
+
+/**
+ * Tolerant parser for the plain `gh pr checks` table, used when the installed
+ * gh build has no `--json` for this command. Tab-separated output is the
+ * documented non-TTY form; space-padded tables are handled as a fallback.
+ */
+export function parseChecksText(value) {
+  const rows = [];
+  for (const rawLine of asString(value).split(/\r?\n/u)) {
+    const line = rawLine.replace(/\u001B\[[0-9;?]*[A-Za-z]/gu, "").trim();
+    if (line.length === 0) continue;
+    if (/^(All checks were successful|No checks reported|no checks)/iu.test(line)) continue;
+    const cells = cellsOf(line).filter((cell, index, all) => !(index === 0 && cell.length === 0));
+    if (cells.length < 2) continue;
+    const bucketIndex = cells.findIndex((cell) => CHECK_BUCKETS.has(cell.toLowerCase()));
+    if (bucketIndex === -1) continue;
+    const name = cells.slice(0, bucketIndex).join(" ").trim() || cells[0];
+    if (name.length === 0) continue;
+    const rest = cells.slice(bucketIndex + 1);
+    const link = rest.find((cell) => /^https?:\/\//iu.test(cell)) ?? "";
+    const duration = rest.find((cell) => /^(?:\d+(?:\.\d+)?(?:ms|s|m|h|d))+$/iu.test(cell)) ?? "";
+    const description = rest
+      .filter((cell) => cell.length > 0 && cell !== link && cell !== duration && !/^-+$/u.test(cell))
+      .join(" ")
+      .trim();
+    rows.push({
+      name,
+      bucket: cells[bucketIndex].toLowerCase(),
+      state: cells[bucketIndex].toUpperCase(),
+      description,
+      link,
+      workflow: "",
+      duration,
+    });
+    if (rows.length >= LIMITS.checks) break;
+  }
+  return rows;
+}
+
+/* ------------------------------------------------------------------ */
+/* Reviews, conversation and inline threads                            */
+/* ------------------------------------------------------------------ */
+
+/** Compact review summary: counts by state and the reviews blocking merge. */
+export function summarizeReviews(reviews) {
+  const list = Array.isArray(reviews) ? reviews.filter(Boolean) : [];
+  const byState = { APPROVED: 0, CHANGES_REQUESTED: 0, COMMENTED: 0, DISMISSED: 0, PENDING: 0, OTHER: 0 };
+  const items = list.map((review) => {
+    const state = asString(review.state).toUpperCase();
+    const key = Object.prototype.hasOwnProperty.call(byState, state) ? state : "OTHER";
+    byState[key] += 1;
+    return {
+      author: loginOf(review.author ?? review.user),
+      state,
+      body: snippet(review.body, LIMITS.commentChars),
+      submittedAt: asString(review.submittedAt ?? review.submitted_at),
+      url: asString(review.url ?? review.html_url),
+    };
+  });
+  const latestByAuthor = new Map();
+  for (const item of items) {
+    if (item.author.length === 0) continue;
+    const previous = latestByAuthor.get(item.author);
+    if (!previous || item.submittedAt >= previous.submittedAt) latestByAuthor.set(item.author, item);
+  }
+  const blocking = [...latestByAuthor.values()].filter((item) => item.state === "CHANGES_REQUESTED");
+  return {
+    total: list.length,
+    byState,
+    items: items.slice(0, LIMITS.conversation),
+    truncated: items.length > LIMITS.conversation,
+    latestByAuthor: [...latestByAuthor.values()],
+    blocking,
+  };
+}
+
+/** Conversation (issue) comments from `gh pr view --json comments`. */
+export function normalizeConversationComments(comments) {
+  const list = Array.isArray(comments) ? comments.filter(Boolean) : [];
+  const items = list.slice(0, LIMITS.conversation).map((comment) => ({
+    author: loginOf(comment.author ?? comment.user),
+    body: snippet(comment.body, LIMITS.commentChars),
+    createdAt: asString(comment.createdAt ?? comment.created_at),
+    url: asString(comment.url ?? comment.html_url),
+  }));
+  return { total: list.length, items, truncated: list.length > items.length };
+}
+
+function commentLogin(row) {
+  return loginOf(row?.user ?? row?.author);
+}
+
+function lineOf(row) {
+  const line = row?.line ?? row?.original_line;
+  const number = Number(line);
+  return Number.isSafeInteger(number) && number > 0 ? number : null;
+}
+
+/** Root comment of a reply chain; tolerates cycles and unknown parents. */
+function threadRootOf(row, byId) {
+  let current = row;
+  const seen = new Set();
+  while (current !== null && typeof current === "object") {
+    const parentId = Number(current.in_reply_to_id);
+    if (!Number.isSafeInteger(parentId) || parentId <= 0 || seen.has(parentId)) break;
+    const parent = byId.get(parentId);
+    if (!parent) break;
+    seen.add(parentId);
+    current = parent;
+  }
+  return current ?? row;
+}
+
+/**
+ * Group REST pull-request review comments into threads. The REST API does not
+ * expose resolved/outdated state; `resolvedKnown: false` records that honestly.
+ */
+export function normalizeReviewComments(rows) {
+  const list = Array.isArray(rows) ? rows.filter(Boolean) : [];
+  const byId = new Map();
+  for (const row of list) {
+    const id = asPositiveInt(row.id);
+    if (id !== undefined) byId.set(id, row);
+  }
+  const threads = [];
+  const open = new Map();
+  for (let index = 0; index < list.length; index += 1) {
+    const row = list[index];
+    const root = threadRootOf(row, byId);
+    const rootId = asPositiveInt(root.id);
+    const key = rootId === undefined ? `row-${index}` : `id-${rootId}`;
+    let thread = open.get(key);
+    if (!thread) {
+      thread = {
+        id: rootId ?? null,
+        path: asString(root.path),
+        line: lineOf(root),
+        side: asString(root.side),
+        author: commentLogin(root),
+        body: snippet(root.body, LIMITS.commentChars),
+        createdAt: asString(root.created_at ?? root.createdAt),
+        url: asString(root.html_url ?? root.url),
+        replies: [],
+      };
+      threads.push(thread);
+      open.set(key, thread);
+      continue;
+    }
+    if (row === root) continue;
+    thread.replies.push({
+      author: commentLogin(row),
+      body: snippet(row.body, LIMITS.commentChars),
+      createdAt: asString(row.created_at ?? row.createdAt),
+      url: asString(row.html_url ?? row.url),
+    });
+  }
+  const byFile = new Map();
+  for (const thread of threads) {
+    const path = thread.path.length > 0 ? thread.path : "(без файла)";
+    byFile.set(path, (byFile.get(path) ?? 0) + 1);
+  }
+  return {
+    total: list.length,
+    threadCount: threads.length,
+    threads: threads.slice(0, LIMITS.threads),
+    replies: list.length - threads.length,
+    truncated: threads.length > LIMITS.threads,
+    byFile: [...byFile.entries()]
+      .map(([path, count]) => ({ path, count }))
+      .sort((left, right) => right.count - left.count || left.path.localeCompare(right.path))
+      .slice(0, 10),
+    resolvedKnown: false,
+  };
+}

package/plugins/dsh-github-review/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "dsh-github-review",
+  "version": "1.0.0",
+  "description": "GitHub pull-request review tool for DSH: gh status, PR overview, CI checks, review comment threads and a byte-capped diff via the gh CLI. Read-only by default; one opt-in, explicitly confirmed comment action. No merge/close/force.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./lib": "./lib/normalize.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib/**",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}