@baiyibai-antora/jira-retriever 1.0.0-beta.5

package/bin/jira-retrieve.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict'
+
+// jira-retrieve: pull Jira issues selected by JQL down as AsciiDoc files.
+// Configuration via jira.yml and/or flags; credentials from the environment.
+
+const fsp = require('node:fs/promises')
+const ospath = require('node:path')
+const yaml = require('js-yaml')
+const { AtlassianClient, credentialsFromEnv } = require('@baiyibai-antora/atlassian-client')
+const { retrieveIssues, DEFAULT_FIELDS } = require('../lib')
+
+const USAGE = `Usage: jira-retrieve [options] [jira.yml]
+
+Writes one .adoc file per issue (KEY.adoc): scalar fields become header
+attributes, the description becomes the body, comments and other rich-text
+fields become sections.
+
+jira.yml:
+  jql: project = DEMO ORDER BY key
+  fields: [summary, description, labels, status, comment]   # ids or names
+  out: issues
+
+Options:
+  --jql <query>      JQL (overrides the config file)
+  --fields <a,b,c>   fields to retrieve (default: ${DEFAULT_FIELDS.join(',')})
+  --out <dir>        output directory (default: ./issues)
+  --keep-colors      keep text/background colors as role spans
+  -h, --help         show this help
+
+Environment: ATLASSIAN_BASE_URL (or JIRA_BASE_URL), ATLASSIAN_EMAIL,
+ATLASSIAN_API_TOKEN`
+
+function parseArgs (argv) {
+  const opts = { jql: null, fields: null, out: null, styles: 'drop', config: null }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '-h' || arg === '--help') return { help: true }
+    else if (arg === '--jql') opts.jql = argv[++i]
+    else if (arg === '--fields') opts.fields = argv[++i].split(',').map((f) => f.trim()).filter(Boolean)
+    else if (arg === '--out') opts.out = argv[++i]
+    else if (arg === '--keep-colors') opts.styles = 'roles'
+    else if (arg.startsWith('-')) throw new Error(`unknown option ${arg}`)
+    else if (opts.config) throw new Error('only one config file may be given')
+    else opts.config = arg
+  }
+  return opts
+}
+
+async function main () {
+  let opts
+  try {
+    opts = parseArgs(process.argv.slice(2))
+  } catch (err) {
+    process.stderr.write(`jira-retrieve: ${err.message}\n${USAGE}\n`)
+    return 1
+  }
+  if (opts.help) {
+    process.stdout.write(USAGE + '\n')
+    return 0
+  }
+
+  let config = {}
+  if (opts.config) config = yaml.load(await fsp.readFile(opts.config, 'utf8')) || {}
+  const jql = opts.jql || config.jql
+  if (!jql) {
+    process.stderr.write(`jira-retrieve: no JQL given (pass --jql or a config file)\n${USAGE}\n`)
+    return 1
+  }
+
+  let client
+  try {
+    client = new AtlassianClient({ ...credentialsFromEnv(), serviceName: 'Jira' })
+  } catch (err) {
+    process.stderr.write(`jira-retrieve: ${err.message}\n`)
+    return 1
+  }
+
+  const logger = { warn: (msg) => process.stderr.write(`jira-retrieve: ${msg}\n`) }
+  const { files, issues } = await retrieveIssues({
+    client,
+    jql,
+    fields: opts.fields || config.fields || undefined,
+    styles: opts.styles,
+    logger,
+  })
+
+  const outDir = opts.out || config.out || 'issues'
+  for (const file of files) {
+    const dest = ospath.join(outDir, ...file.path.split('/'))
+    await fsp.mkdir(ospath.dirname(dest), { recursive: true })
+    await fsp.writeFile(dest, file.contents)
+  }
+  process.stdout.write(`retrieved ${issues.length} issue(s) to ${outDir}\n`)
+  return 0
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code
+  },
+  (err) => {
+    process.stderr.write(`jira-retrieve: ${err.message}\n`)
+    process.exitCode = 1
+  }
+)

package/lib/index.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const { retrieveIssues, DEFAULT_FIELDS } = require('./retrieve')
+
+module.exports = { retrieveIssues, DEFAULT_FIELDS }

package/lib/retrieve.js

@@ -0,0 +1,277 @@
+'use strict'
+
+const { posix: path } = require('node:path')
+const { toAdoc } = require('@baiyibai-antora/asciidoc-adf-converter')
+
+// Retrieve Jira issues selected by JQL as an in-memory AsciiDoc file tree,
+// one file per issue, in the tagged issue format (see the README): the
+// issue is a level-1 section carrying its scalar fields as named block
+// attributes, the description is the section body, and comments, custom
+// rich-text fields, and attachments are tagged subsections. Everything
+// semantic is a walkable node attribute — no document attributes, so files
+// can be concatenated or included without collisions, and jira-publish can
+// consume them.
+//
+// The v3 REST API returns rich-text fields as ADF. Attachments download
+// into _attachments/KEY/. Inline media in ADF reference Media Services
+// UUIDs that no v3 payload maps to attachments; the bridge is the rendered
+// HTML (expand=renderedFields), where the same images appear in document
+// order as /attachment/content/<id> URLs. When the counts line up the
+// media resolve to the downloaded files; otherwise they stay adf-media:
+// placeholders with a warning.
+
+const RICH_DEFAULT = [
+  'summary', 'description', 'issuetype', 'status', 'priority', 'assignee',
+  'reporter', 'labels', 'components', 'fixVersions', 'parent', 'created',
+  'updated', 'comment', 'attachment', 'issuelinks', 'subtasks',
+]
+
+// Noise dropped when `fields: all` expands to *all.
+const ALL_SKIP = new Set([
+  'avatarUrls', 'votes', 'watches', 'worklog', 'progress', 'aggregateprogress',
+  'aggregatetimeestimate', 'aggregatetimeoriginalestimate', 'aggregatetimespent',
+  'timeestimate', 'timeoriginalestimate', 'timespent', 'timetracking',
+  'workratio', 'lastViewed', 'statuscategorychangedate', 'thumbnail',
+  'security', 'environment',
+])
+
+const isAdfDoc = (value) => Boolean(value) && typeof value === 'object' && value.type === 'doc'
+
+function attrValue (value) {
+  if (value == null) return null
+  if (Array.isArray(value)) return value.map(attrValue).filter((v) => v != null).join(', ')
+  if (typeof value === 'object') return value.name || value.displayName || value.key || value.value || null
+  return String(value)
+}
+
+function attrName (field) {
+  return String(field)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+// One `name=value` pair for an AsciiDoc attribute list: quoted unless the
+// value is plainly safe, newlines flattened.
+function attrPair (name, value) {
+  let v = String(value).replace(/\s*\n\s*/g, ' ').trim()
+  if (/[^A-Za-z0-9_.:@/-]/.test(v)) v = `"${v.replace(/"/g, '\\"')}"`
+  return `${name}=${v}`
+}
+
+// System fields keep predictable attribute names regardless of how the
+// site's field catalog displays them; custom fields derive from their name.
+const SYSTEM_ATTR = {
+  issuetype: 'jira-issuetype',
+  status: 'jira-status',
+  priority: 'jira-priority',
+  labels: 'jira-labels',
+  components: 'jira-components',
+  fixVersions: 'jira-fix-versions',
+  created: 'jira-created',
+  updated: 'jira-updated',
+  resolution: 'jira-resolution',
+  duedate: 'jira-duedate',
+  project: 'jira-project',
+}
+
+async function resolveFields (client, wanted) {
+  const catalog = await client.request('GET', '/rest/api/3/field')
+  const byName = new Map((catalog || []).map((f) => [f.name.toLowerCase(), f]))
+  const byId = new Map((catalog || []).map((f) => [f.id, f]))
+  return wanted.map((entry) => {
+    const field = byId.get(entry) || byName.get(String(entry).toLowerCase())
+    if (!field) throw new Error(`unknown Jira field "${entry}" (use an id or the exact display name)`)
+    return { id: field.id, name: field.name }
+  })
+}
+
+// Media Services UUIDs (ADF, document order) zipped against the attachment
+// content ids in the rendered HTML of the same body.
+function walkMediaIds (node, out = []) {
+  if (!node || typeof node !== 'object') return out
+  if (node.type === 'media' || node.type === 'mediaInline') {
+    if ((node.attrs || {}).type === 'file' && node.attrs.id) out.push(node.attrs.id)
+  }
+  for (const child of node.content || []) walkMediaIds(child, out)
+  return out
+}
+
+function mediaMapFor (adf, renderedHtml, attachmentsById, warn, label) {
+  const uuids = walkMediaIds(adf)
+  if (!uuids.length) return new Map()
+  const numeric = [...String(renderedHtml || '').matchAll(/\/attachment\/(?:content|thumbnail)\/(\d+)/g)].map((m) => m[1])
+  if (numeric.length !== uuids.length) {
+    warn(`${label}: ${uuids.length} media node(s) but ${numeric.length} attachment reference(s) in the rendered body; leaving adf-media placeholders`)
+    return new Map()
+  }
+  const map = new Map()
+  uuids.forEach((uuid, i) => {
+    const att = attachmentsById.get(numeric[i])
+    if (att) map.set(uuid, att)
+  })
+  return map
+}
+
+function issueToAdoc (issue, resolved, opts, warn) {
+  const { styles, attachmentDir, attachmentFiles } = opts
+  const values = issue.fields || {}
+  const rendered = issue.renderedFields || {}
+  const key = issue.key
+  const attachments = Array.isArray(values.attachment) ? values.attachment : []
+  const attachmentsById = new Map(attachments.map((att) => [String(att.id), att]))
+
+  const convert = (adf, label, renderedHtml, levelOffset) => {
+    const mediaMap = mediaMapFor(adf, renderedHtml, attachmentsById, warn, `${key} ${label}`)
+    const resolveMedia = ({ id }) => {
+      const att = mediaMap.get(String(id))
+      if (!att) return null
+      attachmentFiles.add(String(att.id))
+      return path.join(attachmentDir, att.filename)
+    }
+    const result = toAdoc(adf, { styles, levelOffset, resolveMedia })
+    for (const warning of result.warnings) warn(`${key} ${label}: ${warning}`)
+    return result.adoc.trimEnd()
+  }
+
+  const attrs = [attrPair('jira', 'issue'), attrPair('jira-key', key)]
+  if (issue.id) attrs.push(attrPair('jira-id', issue.id))
+  attrs.push(attrPair('jira-project', key.replace(/-\d+$/, '')))
+  const sections = []
+  let description = ''
+
+  const push = (name, value) => {
+    const v = attrValue(value)
+    if (v != null && v !== '') attrs.push(attrPair(name, v))
+  }
+
+  for (const field of resolved) {
+    const value = values[field.id]
+    if (field.id === 'summary' || value == null) continue
+    switch (field.id) {
+      case 'description':
+        if (isAdfDoc(value)) description = convert(value, 'description', rendered.description, 1)
+        break
+      case 'comment': {
+        for (const comment of (value.comments || []).filter((c) => isAdfDoc(c.body))) {
+          const author = (comment.author && comment.author.displayName) || 'unknown'
+          const date = comment.created ? String(comment.created).slice(0, 10) : ''
+          const cAttrs = [attrPair('jira', 'comment'), attrPair('jira-id', comment.id)]
+          cAttrs.push(attrPair('jira-author', author))
+          if (comment.author && comment.author.accountId) cAttrs.push(attrPair('jira-author-id', comment.author.accountId))
+          if (comment.created) cAttrs.push(attrPair('jira-created', comment.created))
+          const renderedBody = ((rendered.comment || {}).comments || []).find((c) => String(c.id) === String(comment.id))
+          sections.push(
+            `[${cAttrs.join(',')}]\n=== ${author}${date ? ` (${date})` : ''}\n\n` +
+            convert(comment.body, `comment ${comment.id}`, renderedBody && renderedBody.body, 2)
+          )
+        }
+        break
+      }
+      case 'attachment': {
+        if (!attachments.length) break
+        const items = attachments.map((att) => {
+          attachmentFiles.add(String(att.id))
+          const target = path.join(attachmentDir, att.filename)
+          const size = att.size >= 1024 ? `${Math.round(att.size / 1024)} KB` : `${att.size} B`
+          const author = (att.author && att.author.displayName) || 'unknown'
+          const date = att.created ? String(att.created).slice(0, 10) : ''
+          return `* link:${target}[${att.filename}] (${att.mimeType || 'unknown'}, ${size}, ${author}${date ? `, ${date}` : ''})`
+        })
+        sections.push(`[jira=attachments]\n=== Attachments\n\n${items.join('\n')}`)
+        break
+      }
+      case 'assignee':
+      case 'reporter':
+        push(`jira-${field.id}`, value.displayName)
+        if (value.accountId) push(`jira-${field.id}-id`, value.accountId)
+        break
+      case 'parent':
+        push('jira-parent', value.key)
+        break
+      case 'issuelinks': {
+        const links = value
+          .map((link) => {
+            if (link.outwardIssue) return `${link.type.outward} ${link.outwardIssue.key}`
+            if (link.inwardIssue) return `${link.type.inward} ${link.inwardIssue.key}`
+            return null
+          })
+          .filter(Boolean)
+        if (links.length) attrs.push(attrPair('jira-links', links.join('; ')))
+        break
+      }
+      case 'subtasks':
+        if (value.length) push('jira-subtasks', value.map((s) => s.key).join(', '))
+        break
+      default:
+        if (isAdfDoc(value)) {
+          sections.push(
+            `[${attrPair('jira', 'field')},${attrPair('jira-field-name', field.name)}]\n=== ${field.name}\n\n` +
+            convert(value, field.name, rendered[field.id], 2)
+          )
+        } else {
+          push(SYSTEM_ATTR[field.id] || `jira-${attrName(field.name)}`, value)
+        }
+    }
+  }
+
+  const summary = values.summary || key
+  const parts = [`[${attrs.join(',')}]\n== ${key}: ${summary}`, description, ...sections].filter(Boolean)
+  return parts.join('\n\n') + '\n'
+}
+
+async function retrieveIssues ({ client, jql, fields, styles, logger }) {
+  const warnings = []
+  const warn = (msg) => {
+    warnings.push(msg)
+    if (logger) logger.warn(msg)
+  }
+  if (!jql) throw new Error('a jql query is required')
+
+  let resolved
+  let fieldParam
+  if (fields === 'all' || (Array.isArray(fields) && fields.length === 1 && fields[0] === 'all')) {
+    const catalog = await client.request('GET', '/rest/api/3/field')
+    resolved = (catalog || [])
+      .filter((f) => !ALL_SKIP.has(f.id))
+      .map((f) => ({ id: f.id, name: f.name }))
+    fieldParam = '*all'
+  } else {
+    resolved = await resolveFields(client, fields || RICH_DEFAULT)
+    if (!resolved.some((f) => f.id === 'summary')) resolved.unshift({ id: 'summary', name: 'Summary' })
+    fieldParam = resolved.map((f) => f.id).join(',')
+  }
+
+  const files = []
+  const issues = []
+  let pageToken
+  do {
+    const params = new URLSearchParams({ jql, fields: fieldParam, maxResults: '100', expand: 'renderedFields' })
+    if (pageToken) params.set('nextPageToken', pageToken)
+    const page = await client.request('GET', `/rest/api/3/search/jql?${params}`)
+    for (const issue of (page && page.issues) || []) {
+      const attachmentDir = path.join('_attachments', issue.key)
+      const attachmentFiles = new Set()
+      const contents = issueToAdoc(issue, resolved, { styles, attachmentDir, attachmentFiles }, warn)
+
+      for (const att of (issue.fields || {}).attachment || []) {
+        if (!attachmentFiles.has(String(att.id)) || !att.content) continue
+        const bytes = await client.download(String(att.content).replace(client.baseUrl, ''))
+        if (bytes) {
+          files.push({ path: path.join(attachmentDir, att.filename), contents: bytes })
+        } else {
+          warn(`${issue.key}: attachment ${att.filename} could not be downloaded`)
+        }
+      }
+
+      const filePath = `${issue.key}.adoc`
+      files.push({ path: filePath, contents })
+      issues.push({ key: issue.key, path: filePath, summary: (issue.fields || {}).summary || issue.key })
+    }
+    pageToken = page && page.nextPageToken
+  } while (pageToken)
+
+  return { files, issues, warnings }
+}
+
+module.exports = { retrieveIssues, DEFAULT_FIELDS: RICH_DEFAULT }

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@baiyibai-antora/jira-retriever",
+  "version": "1.0.0-beta.5",
+  "description": "Retrieve Jira Cloud issues as AsciiDoc: JQL selection over the v3 REST API, rich-text fields arrive as ADF and convert with @baiyibai-antora/asciidoc-adf-converter",
+  "license": "MIT",
+  "author": "baiyibai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/baiyibai-antora/confluora.git",
+    "directory": "packages/jira-retriever"
+  },
+  "type": "commonjs",
+  "main": "lib/index.js",
+  "bin": {
+    "jira-retrieve": "bin/jira-retrieve.js"
+  },
+  "files": [
+    "lib",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test test/*-test.js"
+  },
+  "dependencies": {
+    "@baiyibai-antora/asciidoc-adf-converter": "^1.0.0-beta.5",
+    "@baiyibai-antora/atlassian-client": "^1.0.0-beta.5",
+    "js-yaml": "^4.1.0"
+  },
+  "keywords": [
+    "confluora",
+    "jira",
+    "asciidoc",
+    "adf",
+    "issues",
+    "retriever"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}