@greeana/jira-dev-workflow 0.1.0

package/src/issue-search.ts

@@ -0,0 +1,129 @@
+import { createJiraClient, getIssueSearchText, getIssueStatusCategoryKey, getIssueSummary, type JiraIssue } from "./jira-client";
+
+export type RankedIssue = {
+  issueKey: string;
+  score: number;
+  status: string;
+  statusCategory: string;
+  summary: string;
+  updated?: string;
+  url: string;
+};
+
+export type IssueSearchResult = {
+  closedMatches: RankedIssue[];
+  openMatches: RankedIssue[];
+  recommendedAction: "reuse-open" | "create-related-to-closed" | "create-new";
+  recommendedClosedIssueKey: string | null;
+  recommendedOpenIssueKey: string | null;
+};
+
+export function buildSearchJql(projectKey: string, searchText: string): string {
+  const tokens = tokenizeSearchText(searchText).slice(0, 8);
+  const queryTokens = tokens.length > 0 ? tokens : searchText.split(/\s+/).map((token) => token.trim()).filter(Boolean);
+
+  if (queryTokens.length === 0) {
+    throw new Error("Could not build a Jira query from empty search text.");
+  }
+
+  const tokenClauses = queryTokens.slice(0, 8).map((token) => `text ~ "${escapeJqlValue(token)}"`);
+  const query = tokenClauses.join(" OR ");
+  return `project = "${escapeJqlValue(projectKey)}" AND (${query}) ORDER BY updated DESC`;
+}
+
+export function tokenizeSearchText(searchText: string): string[] {
+  const stopWords = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "into",
+    "that",
+    "this",
+    "have",
+    "your",
+    "will",
+    "make",
+    "add",
+    "use",
+  ]);
+
+  const seen = new Set<string>();
+  const tokens: string[] = [];
+
+  for (const token of searchText.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (token.length < 3 || stopWords.has(token) || seen.has(token)) {
+      continue;
+    }
+
+    seen.add(token);
+    tokens.push(token);
+  }
+
+  return tokens;
+}
+
+export function rankIssues(
+  issues: JiraIssue[],
+  searchText: string,
+  jira: Pick<ReturnType<typeof createJiraClient>, "getIssueBrowseUrl">,
+): RankedIssue[] {
+  const tokens = tokenizeSearchText(searchText);
+
+  return issues
+    .map((issue) => {
+      const haystack = getIssueSearchText(issue).toLowerCase();
+      const score = tokens.reduce((count, token) => count + (haystack.includes(token) ? 1 : 0), 0);
+      const statusCategory = getIssueStatusCategoryKey(issue) ?? "unknown";
+
+      return {
+        issueKey: issue.key,
+        score,
+        status: issue.fields.status?.name ?? "Unknown",
+        statusCategory,
+        summary: getIssueSummary(issue),
+        updated: issue.fields.updated,
+        url: jira.getIssueBrowseUrl(issue.key),
+      };
+    })
+    .sort((left, right) => {
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+
+      return (right.updated ?? "").localeCompare(left.updated ?? "");
+    });
+}
+
+export async function searchIssuesForText(input: {
+  jira: ReturnType<typeof createJiraClient>;
+  limit: number;
+  projectKey: string;
+  searchText: string;
+}): Promise<IssueSearchResult> {
+  const { jira, limit, projectKey, searchText } = input;
+  const jql = buildSearchJql(projectKey, searchText);
+  const issues = await jira.searchIssues(jql, Math.max(limit * 3, 15), [
+    "summary",
+    "status",
+    "description",
+    "updated",
+  ]);
+
+  const ranked = rankIssues(issues, searchText, jira);
+  const openMatches = ranked.filter((issue) => issue.statusCategory !== "done").slice(0, limit);
+  const closedMatches = ranked.filter((issue) => issue.statusCategory === "done").slice(0, limit);
+
+  return {
+    closedMatches,
+    openMatches,
+    recommendedAction: openMatches.length > 0 ? "reuse-open" : closedMatches.length > 0 ? "create-related-to-closed" : "create-new",
+    recommendedClosedIssueKey: openMatches.length === 0 ? closedMatches[0]?.issueKey ?? null : null,
+    recommendedOpenIssueKey: openMatches[0]?.issueKey ?? null,
+  };
+}
+
+function escapeJqlValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/src/jira-client.ts

@@ -0,0 +1,325 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { AdfDocument } from "./csv";
+import { adfToPlainText } from "./csv";
+import { readEnv } from "./config";
+
+export type JiraCurrentUser = {
+  accountId?: string;
+  displayName?: string;
+  emailAddress?: string;
+  self?: string;
+};
+
+export type JiraIssueStatus = {
+  name: string;
+  statusCategory?: {
+    key?: string;
+    name?: string;
+  };
+};
+
+export type JiraIssue = {
+  key: string;
+  self?: string;
+  fields: {
+    description?: unknown;
+    issuetype?: { name?: string };
+    status?: JiraIssueStatus;
+    summary?: string;
+    updated?: string;
+  };
+};
+
+export type JiraProject = {
+  id: string;
+  key: string;
+  name: string;
+  projectTypeKey?: string;
+  simplified?: boolean;
+  style?: string;
+};
+
+type JiraCreateIssueResponse = {
+  id: string;
+  key: string;
+};
+
+type JiraErrorResponse = {
+  errorMessages?: string[];
+  errors?: Record<string, string>;
+};
+
+type JiraPermissionsResponse = {
+  permissions?: Record<
+    string,
+    {
+      havePermission: boolean;
+      id: string;
+      key: string;
+      name: string;
+      type: string;
+    }
+  >;
+};
+
+type JiraSearchResponse = {
+  issues?: JiraIssue[];
+};
+
+export type JiraAttachment = {
+  content?: string;
+  created?: string;
+  filename?: string;
+  id?: number | string;
+  mimeType?: string;
+  self?: string;
+  size?: number;
+  thumbnail?: string;
+};
+
+export function createJiraClient() {
+  const baseUrl = readEnv("JIRA_BASE_URL");
+
+  if (!baseUrl) {
+    throw new Error("Set JIRA_BASE_URL in .jira-dev-workflow/.env.local or in the environment before running jira-dev-workflow.");
+  }
+
+  const email = readEnv("JIRA_EMAIL");
+  const apiToken = readEnv("JIRA_API_TOKEN");
+
+  if (!email || !apiToken) {
+    throw new Error("Set JIRA_EMAIL and JIRA_API_TOKEN in .jira-dev-workflow/.env.local or in the environment before running jira-dev-workflow.");
+  }
+
+  const authHeader = `Basic ${Buffer.from(`${email}:${apiToken}`).toString("base64")}`;
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
+
+  return {
+    addComment(issueKey: string, comment: AdfDocument) {
+      return jiraRequest<void>(normalizedBaseUrl, authHeader, `/rest/api/3/issue/${issueKey}/comment`, {
+        body: JSON.stringify({ body: comment }),
+        method: "POST",
+      });
+    },
+
+    addIssueLink(inwardIssueKey: string, outwardIssueKey: string, linkTypeName: string) {
+      return jiraRequest<void>(normalizedBaseUrl, authHeader, "/rest/api/3/issueLink", {
+        body: JSON.stringify({
+          inwardIssue: { key: inwardIssueKey },
+          outwardIssue: { key: outwardIssueKey },
+          type: { name: linkTypeName },
+        }),
+        method: "POST",
+      });
+    },
+
+    async attachFile(issueKey: string, filePath: string): Promise<JiraAttachment[]> {
+      const fileName = path.basename(filePath);
+      const bytes = await fs.readFile(filePath);
+      const formData = new FormData();
+      formData.append("file", new Blob([bytes]), fileName);
+
+      return fetch(`${normalizedBaseUrl}/rest/api/3/issue/${issueKey}/attachments`, {
+        body: formData,
+        headers: {
+          Accept: "application/json",
+          Authorization: authHeader,
+          "X-Atlassian-Token": "no-check",
+        },
+        method: "POST",
+      }).then(async (response) => {
+        const rawBody = await response.text();
+        const parsedBody = rawBody ? safeJsonParse(rawBody) : null;
+
+        if (!response.ok) {
+          const details = formatJiraError(parsedBody, rawBody);
+          throw new Error(`${response.status} ${response.statusText}${details ? `: ${details}` : ""}`);
+        }
+
+        return Array.isArray(parsedBody) ? (parsedBody as JiraAttachment[]) : [];
+      });
+    },
+
+    createIssue(input: {
+      description?: AdfDocument | null;
+      issueType: string;
+      labels?: string[];
+      projectKey: string;
+      summary: string;
+    }) {
+      const fields: Record<string, unknown> = {
+        issuetype: { name: input.issueType },
+        project: { key: input.projectKey },
+        summary: input.summary,
+      };
+
+      if (input.description) {
+        fields.description = input.description;
+      }
+
+      if (input.labels?.length) {
+        fields.labels = input.labels;
+      }
+
+      return jiraRequest<JiraCreateIssueResponse>(normalizedBaseUrl, authHeader, "/rest/api/3/issue", {
+        body: JSON.stringify({ fields }),
+        method: "POST",
+      });
+    },
+
+    getCurrentUser() {
+      return jiraRequest<JiraCurrentUser>(normalizedBaseUrl, authHeader, "/rest/api/3/myself", {
+        method: "GET",
+      });
+    },
+
+    getIssue(issueKey: string) {
+      return jiraRequest<JiraIssue>(normalizedBaseUrl, authHeader, `/rest/api/3/issue/${issueKey}`, {
+        method: "GET",
+      });
+    },
+
+    getIssueBrowseUrl(issueKey: string) {
+      return `${normalizedBaseUrl}/browse/${issueKey}`;
+    },
+
+    getMyPermissions(projectKey: string, permissionKeys: string[]) {
+      const searchParams = new URLSearchParams({
+        permissions: permissionKeys.join(","),
+        projectKey,
+      });
+
+      return jiraRequest<JiraPermissionsResponse>(
+        normalizedBaseUrl,
+        authHeader,
+        `/rest/api/3/mypermissions?${searchParams.toString()}`,
+        { method: "GET" },
+      );
+    },
+
+    getProject(projectKey: string) {
+      return jiraRequest<JiraProject>(
+        normalizedBaseUrl,
+        authHeader,
+        `/rest/api/3/project/${encodeURIComponent(projectKey)}`,
+        { method: "GET" },
+      );
+    },
+
+    async searchIssues(jql: string, maxResults: number, fields: string[]) {
+      const response = await jiraRequest<JiraSearchResponse>(normalizedBaseUrl, authHeader, "/rest/api/3/search/jql", {
+        body: JSON.stringify({
+          fields,
+          jql,
+          maxResults,
+        }),
+        method: "POST",
+      });
+
+      return response.issues ?? [];
+    },
+
+    async resolveMediaIdFromAttachmentContentUrl(contentUrl: string) {
+      const absoluteUrl = toAbsoluteUrl(normalizedBaseUrl, contentUrl);
+      const response = await fetch(absoluteUrl, {
+        headers: {
+          Accept: "*/*",
+          Authorization: authHeader,
+        },
+        method: "GET",
+        redirect: "manual",
+      });
+
+      const location = response.headers.get("location");
+
+      if (!location) {
+        throw new Error(`Could not resolve media ID from attachment redirect for ${contentUrl}. No Location header returned.`);
+      }
+
+      const mediaId = extractMediaIdFromLocation(location);
+
+      if (!mediaId) {
+        throw new Error(`Could not extract media ID from attachment redirect location: ${location}`);
+      }
+
+      return mediaId;
+    },
+  };
+}
+
+export function getIssueStatusCategoryKey(issue: JiraIssue): string | undefined {
+  return issue.fields.status?.statusCategory?.key;
+}
+
+export function getIssueSummary(issue: JiraIssue): string {
+  return issue.fields.summary ?? "";
+}
+
+export function getIssueSearchText(issue: JiraIssue): string {
+  return [issue.fields.summary ?? "", adfToPlainText(issue.fields.description)].join("\n");
+}
+
+async function jiraRequest<T>(
+  baseUrl: string,
+  authHeader: string,
+  apiPath: string,
+  init: RequestInit,
+): Promise<T> {
+  const response = await fetch(`${baseUrl}${apiPath}`, {
+    ...init,
+    headers: {
+      Accept: "application/json",
+      Authorization: authHeader,
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+
+  if (response.status === 204) {
+    return undefined as T;
+  }
+
+  const rawBody = await response.text();
+  const parsedBody = rawBody ? safeJsonParse(rawBody) : null;
+
+  if (!response.ok) {
+    const details = formatJiraError(parsedBody, rawBody);
+    throw new Error(`${response.status} ${response.statusText}${details ? `: ${details}` : ""}`);
+  }
+
+  return (parsedBody ?? undefined) as T;
+}
+
+function safeJsonParse(input: string): unknown {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+function formatJiraError(parsedBody: unknown, rawBody: string): string {
+  if (parsedBody && typeof parsedBody === "object") {
+    const body = parsedBody as JiraErrorResponse;
+    const messages = body.errorMessages ?? [];
+    const fieldErrors = Object.entries(body.errors ?? {}).map(([field, message]) => `${field}: ${message}`);
+    return [...messages, ...fieldErrors].join("; ");
+  }
+
+  return rawBody.trim();
+}
+
+function toAbsoluteUrl(baseUrl: string, maybeRelativeUrl: string): string {
+  if (/^https?:\/\//i.test(maybeRelativeUrl)) {
+    return maybeRelativeUrl;
+  }
+
+  return `${baseUrl}${maybeRelativeUrl.startsWith("/") ? "" : "/"}${maybeRelativeUrl}`;
+}
+
+function extractMediaIdFromLocation(location: string): string | null {
+  const match = location.match(/\/file\/([0-9a-fA-F-]{36})\//);
+  return match?.[1] ?? null;
+}

package/src/prepare-commit-draft.ts

@@ -0,0 +1,164 @@
+import type { RankedIssue } from "./issue-search";
+
+type DraftInput = {
+  changedFiles: string[];
+  openMatches: RankedIssue[];
+  patchHighlights: string[];
+};
+
+const genericTokens = new Set([
+  "app",
+  "apps",
+  "component",
+  "components",
+  "const",
+  "default",
+  "export",
+  "file",
+  "files",
+  "function",
+  "import",
+  "index",
+  "json",
+  "lib",
+  "node",
+  "page",
+  "path",
+  "return",
+  "route",
+  "src",
+  "test",
+  "tests",
+  "ts",
+  "tsx",
+  "type",
+  "types",
+  "update",
+  "use",
+  "utils",
+  "var",
+]);
+
+const acronyms = new Map([
+  ["api", "API"],
+  ["cta", "CTA"],
+  ["html", "HTML"],
+  ["jira", "Jira"],
+  ["openai", "OpenAI"],
+  ["qa", "QA"],
+  ["ui", "UI"],
+]);
+
+export function buildIssueSummaryDraft(input: DraftInput): string {
+  const areaPhrase = buildAreaPhrase(input.changedFiles, input.patchHighlights);
+
+  if (!areaPhrase) {
+    return input.changedFiles.length === 1
+      ? `Update ${humanizeFileLabel(input.changedFiles[0])}`
+      : "Update staged changes";
+  }
+
+  const topOpenMatch = input.openMatches[0];
+
+  if (topOpenMatch && topOpenMatch.score >= 2) {
+    return topOpenMatch.summary;
+  }
+
+  return `Update ${areaPhrase}`;
+}
+
+export function buildIssueDescriptionDraft(input: { changedFiles: string[]; patchHighlights: string[] }): string {
+  const lines: string[] = ["Prepared from the current diff.", "", "Changed files:"];
+
+  for (const filePath of input.changedFiles.slice(0, 12)) {
+    lines.push(`- ${filePath}`);
+  }
+
+  if (input.changedFiles.length > 12) {
+    lines.push(`- ...and ${input.changedFiles.length - 12} more files`);
+  }
+
+  if (input.patchHighlights.length > 0) {
+    lines.push("", "Patch highlights:");
+
+    for (const highlight of input.patchHighlights.slice(0, 12)) {
+      lines.push(`- ${truncateLine(highlight, 140)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function buildAreaPhrase(changedFiles: string[], patchHighlights: string[]): string {
+  const tokenWeights = new Map<string, number>();
+
+  for (const filePath of changedFiles) {
+    for (const token of tokenize(filePath)) {
+      tokenWeights.set(token, (tokenWeights.get(token) ?? 0) + 3);
+    }
+  }
+
+  for (const highlight of patchHighlights) {
+    for (const token of tokenize(highlight)) {
+      tokenWeights.set(token, (tokenWeights.get(token) ?? 0) + 1);
+    }
+  }
+
+  const tokens = [...tokenWeights.entries()]
+    .filter(([token]) => !genericTokens.has(token))
+    .sort((left, right) => {
+      if (right[1] !== left[1]) {
+        return right[1] - left[1];
+      }
+
+      return left[0].localeCompare(right[0]);
+    })
+    .map(([token]) => token)
+    .slice(0, 4);
+
+  if (tokens.length === 0) {
+    return "";
+  }
+
+  return tokens.map(formatToken).join(" ");
+}
+
+function tokenize(input: string): string[] {
+  const normalized = input
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase();
+
+  return normalized
+    .split(/[^a-z0-9]+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2);
+}
+
+function formatToken(token: string): string {
+  const acronym = acronyms.get(token);
+
+  if (acronym) {
+    return acronym;
+  }
+
+  return token;
+}
+
+function humanizeFileLabel(filePath?: string): string {
+  if (!filePath) {
+    return "staged file";
+  }
+
+  const segments = filePath.split(/[\\/]/).filter(Boolean);
+  const fileName = segments[segments.length - 1] ?? filePath;
+  const withoutExtension = fileName.replace(/\.[^.]+$/, "");
+  return withoutExtension.replace(/[-_]+/g, " ");
+}
+
+function truncateLine(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+
+  return `${text.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}