agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/integrations/atlassian_sync_action.js

@@ -0,0 +1,576 @@
+#!/usr/bin/env node
+/**
+ * scripts/integrations/atlassian_sync_action.js
+ * 
+ * Sincronizador Automático Git ↔ Atlassian via Actions & Local (AGDEV-23 / AGDEV-35).
+ * Conecta automaticamente commits, branches, Pull Requests e páginas do Confluence
+ * aos cards do Jira utilizando a API oficial de Remote Links do Jira Cloud (REST API v3).
+ * 
+ * Governança: Tríade Git + Jira + Confluence (Regra 11 e Regra 15).
+ * Conformidade: OASIS SARIF v2.1.0, Programação Defensiva e Clean Code.
+ */
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const {
+  getAtlassianCredentials,
+  getGitMetadata,
+  getGitRepositoryUrl,
+  requestAtlassian,
+  AtlassianClient
+} = require('./atlassian_client.js');
+
+const { validateRule15 } = require('./credentials_guard.js');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+/**
+ * Obtém a credencial em base64 da Atlassian para compatibilidade retroativa.
+ * @returns {string|null}
+ */
+function getAuth() {
+  const cfg = getAtlassianCredentials();
+  return cfg.authBase64;
+}
+
+/**
+ * Extrai chaves de tickets Jira (ex: AGDEV-123, PROJ-456) a partir de um texto.
+ * Case-insensitive na leitura com normalização em maiúsculas e deduplicação.
+ * @param {string} text 
+ * @returns {Array<string>}
+ */
+function extractIssueKeys(text) {
+  if (!text || typeof text !== 'string') return [];
+  const matches = text.match(/\b[A-Za-z]{2,10}-\d+\b/g) || [];
+  return [...new Set(matches.map(k => k.toUpperCase()))];
+}
+
+/**
+ * Extrai o identificador numérico de um Pull Request (#123, pull request #123 ou URL /pull/123).
+ * @param {string} text 
+ * @returns {string|null}
+ */
+function extractPrNumber(text) {
+  if (!text || typeof text !== 'string') return null;
+  const match = text.match(/#(\d+)\b/) ||
+                text.match(/pull request #(\d+)/i) ||
+                text.match(/\/pull\/(\d+)\b/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Formata o payload canônico de Remote Link para a API v3 do Jira Cloud.
+ * @param {string} url 
+ * @param {string} title 
+ * @param {string} [type='commit'] 
+ * @param {string|null} [globalId=null] 
+ * @param {string|null} [summary=null] 
+ * @returns {object}
+ */
+function formatRemoteLinkPayload(url, title, type = 'commit', globalId = null, summary = null) {
+  const safeType = (typeof type === 'string') ? type.toLowerCase() : 'commit';
+  let iconUrl = 'https://github.githubassets.com/favicons/favicon.png';
+  let iconTitle = `GitHub ${safeType.toUpperCase()}`;
+  let relationship = 'causes';
+
+  if (safeType === 'pr') {
+    relationship = 'relates to';
+  } else if (safeType === 'branch') {
+    relationship = 'builds';
+  } else if (safeType === 'confluence' || safeType === 'wiki') {
+    relationship = undefined;
+    iconUrl = 'https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/confluence.png';
+    iconTitle = 'Confluence Page';
+  }
+
+  const payload = {
+    object: {
+      url: typeof url === 'string' ? url : '',
+      title: typeof title === 'string' ? title : '',
+      icon: {
+        url16x16: iconUrl,
+        title: iconTitle
+      }
+    }
+  };
+
+  if (relationship) {
+    payload.relationship = relationship;
+  }
+  if (globalId) {
+    payload.globalId = globalId;
+  }
+  if (summary) {
+    payload.object.summary = summary;
+  }
+
+  return payload;
+}
+
+/**
+ * Vincula uma página do Confluence como Remote Link em uma issue do Jira.
+ * @param {string} issueKey 
+ * @param {string} pageUrl 
+ * @param {string} pageTitle 
+ * @param {string|null} [summary=null] 
+ * @returns {Promise<object>}
+ */
+async function linkConfluencePageToJira(issueKey, pageUrl, pageTitle, summary = null) {
+  const atlassian = getAtlassianCredentials();
+  const globalId = `system=confluence&pageUrl=${encodeURIComponent(pageUrl)}`;
+  return await linkUrlToJira(
+    issueKey,
+    pageUrl,
+    pageTitle,
+    'confluence',
+    atlassian.authBase64,
+    globalId,
+    summary
+  );
+}
+
+/**
+ * Registra um Remote Link genérico (commit, branch, PR ou doc) em uma issue do Jira.
+ * @param {string} issueKey 
+ * @param {string} url 
+ * @param {string} title 
+ * @param {string} [type='commit'] 
+ * @param {string|null} [authOverride=null] 
+ * @param {string|null} [globalId=null] 
+ * @param {string|null} [summary=null] 
+ * @returns {Promise<object>}
+ */
+async function linkUrlToJira(issueKey, url, title, type = 'commit', authOverride = null, globalId = null, summary = null) {
+  const atlassian = getAtlassianCredentials();
+  const auth = (authOverride !== null && authOverride !== undefined) ? authOverride : atlassian.authBase64;
+  if (!auth) {
+    return { status: 'FAILED', message: 'Credenciais Atlassian não configuradas no ambiente (Regra 15).' };
+  }
+
+  const cleanDomain = atlassian.domain;
+  if (!cleanDomain) {
+    return { status: 'FAILED', message: 'Domínio Atlassian não configurado para este projeto (Regra 15).' };
+  }
+
+  const payload = formatRemoteLinkPayload(url, title, type, globalId, summary);
+  const endpoint = `/rest/api/3/issue/${encodeURIComponent(issueKey)}/remotelink`;
+
+  try {
+    const creds = {
+      domain: cleanDomain,
+      auth,
+      authBase64: auth
+    };
+    const res = await requestAtlassian(creds, 'POST', endpoint, payload);
+
+    if (res.status === 200 || res.status === 201) {
+      return { status: 'SUCCESS', issueKey, url, type, httpStatus: res.status };
+    } else {
+      const errText = typeof res.body === 'object' ? JSON.stringify(res.body) : String(res.body || '');
+      return { status: 'FAILED', issueKey, error: `HTTP ${res.status}: ${errText}` };
+    }
+  } catch (err) {
+    return { status: 'ERROR', issueKey, error: err.message };
+  }
+}
+
+/**
+ * Sincroniza o contexto atual de Git (commit HEAD, branch atual e PR se detectado).
+ * @param {string} [targetDir=process.cwd()] 
+ * @returns {Promise<object>}
+ */
+async function syncCurrentContext(targetDir = process.cwd()) {
+  const atlassian = getAtlassianCredentials(targetDir);
+  const gitMeta = getGitMetadata();
+  const repoUrl = gitMeta.repoUrl || 'https://github.com/ContalApps/agent-master-devsecops';
+  const repoSlug = repoUrl.replace('https://github.com/', '');
+
+  const sha = gitMeta.sha;
+  const branch = gitMeta.branch;
+  const message = gitMeta.message;
+  const prNumber = process.env.PR_NUMBER || extractPrNumber(process.env.PR_TITLE || '') || extractPrNumber(message);
+
+  const combined = `${branch} ${message} ${process.env.PR_TITLE || ''}`;
+  const keys = extractIssueKeys(combined);
+
+  if (keys.length === 0) {
+    return {
+      synced: false,
+      keys: [],
+      reason: 'Nenhuma chave Jira encontrada na branch ou mensagem de commit.',
+      results: []
+    };
+  }
+
+  const results = [];
+
+  for (const key of keys) {
+    if (sha && repoUrl) {
+      const commitGlobalId = `system=github&repo=${repoSlug}&type=commit&sha=${sha}`;
+      const commitRes = await linkUrlToJira(
+        key,
+        `${repoUrl}/commit/${sha}`,
+        `GitHub Commit: ${sha.slice(0, 7)} (${message})`,
+        'commit',
+        atlassian.authBase64,
+        commitGlobalId
+      );
+      results.push({ key, type: 'commit', ref: sha.slice(0, 7), status: commitRes.status, detail: commitRes });
+    }
+
+    if (branch && branch !== 'main' && branch !== 'HEAD' && repoUrl) {
+      const branchGlobalId = `system=github&repo=${repoSlug}&type=branch&name=${branch}`;
+      const branchRes = await linkUrlToJira(
+        key,
+        `${repoUrl}/tree/${branch}`,
+        `GitHub Branch: ${branch}`,
+        'branch',
+        atlassian.authBase64,
+        branchGlobalId
+      );
+      results.push({ key, type: 'branch', ref: branch, status: branchRes.status, detail: branchRes });
+    }
+
+    if (prNumber && repoUrl) {
+      const prGlobalId = `system=github&repo=${repoSlug}&type=pr&id=${prNumber}`;
+      const prRes = await linkUrlToJira(
+        key,
+        `${repoUrl}/pull/${prNumber}`,
+        `GitHub Pull Request #${prNumber}`,
+        'pr',
+        atlassian.authBase64,
+        prGlobalId,
+        process.env.PR_TITLE || message
+      );
+      results.push({ key, type: 'pr', ref: `#${prNumber}`, status: prRes.status, detail: prRes });
+    }
+  }
+
+  return {
+    synced: true,
+    keys,
+    results
+  };
+}
+
+/**
+ * Executa a sincronização retroativa (backfill) de commits recentes.
+ * @param {number} [limit=30] 
+ * @returns {Promise<Array<object>>}
+ */
+async function backfillHistory(limit = 30) {
+  console.log(`[Atlassian Sync] Iniciando sincronização retroativa dos últimos ${limit} commits...`);
+  const atlassian = getAtlassianCredentials();
+  if (!atlassian.isConfigured) {
+    throw new Error('Credenciais Atlassian ausentes para sincronização retroativa.');
+  }
+
+  const repoUrl = getGitRepositoryUrl();
+  const repoSlug = repoUrl.replace('https://github.com/', '');
+
+  let rawLog = '';
+  try {
+    rawLog = execFileSync('git', ['log', `-${limit}`, '--format=%H|%s'], { encoding: 'utf8' });
+  } catch (err) {
+    console.error('[Atlassian Sync] Falha ao extrair histórico git:', err.message);
+    return [];
+  }
+
+  const lines = rawLog.split('\n').filter(l => l.trim().length > 0);
+  const results = [];
+
+  for (const line of lines) {
+    const [sha, ...subjectParts] = line.split('|');
+    const subject = subjectParts.join('|');
+    const keys = extractIssueKeys(subject);
+    const prNumber = extractPrNumber(subject);
+
+    for (const key of keys) {
+      // 1. Link Commit
+      const commitGlobalId = `system=github&repo=${repoSlug}&type=commit&sha=${sha}`;
+      const commitRes = await linkUrlToJira(
+        key,
+        `${repoUrl}/commit/${sha}`,
+        `GitHub Commit: ${sha.slice(0, 7)} (${subject})`,
+        'commit',
+        atlassian.authBase64,
+        commitGlobalId
+      );
+      results.push({ key, type: 'commit', ref: sha.slice(0, 7), status: commitRes.status });
+
+      // 2. Link PR se presente no commit title
+      if (prNumber) {
+        const prGlobalId = `system=github&repo=${repoSlug}&type=pr&id=${prNumber}`;
+        const prRes = await linkUrlToJira(
+          key,
+          `${repoUrl}/pull/${prNumber}`,
+          `GitHub Pull Request #${prNumber}`,
+          'pr',
+          atlassian.authBase64,
+          prGlobalId,
+          subject
+        );
+        results.push({ key, type: 'pr', ref: `#${prNumber}`, status: prRes.status });
+      }
+    }
+  }
+
+  const successCount = results.filter(r => r.status === 'SUCCESS').length;
+  console.log(`[Atlassian Sync] Sincronização retroativa concluída: ${successCount}/${results.length} links processados com sucesso.`);
+  return results;
+}
+
+/**
+ * Formata um relatório executivo em Markdown com o resultado da sincronização de links.
+ * @param {object} [syncSummary={}] 
+ * @returns {string}
+ */
+function formatReport(syncSummary = {}) {
+  let md = '# 🔗 Atlassian Sync Action — Remote Links Status Report\n\n';
+
+  const keys = syncSummary.keys || [];
+  const results = syncSummary.results || [];
+
+  md += `**Chaves Jira Vinculadas:** \`${keys.length > 0 ? keys.join(', ') : 'NENHUMA'}\`\n`;
+  md += `**Total de Links Processados:** \`${results.length}\`\n\n`;
+
+  if (results.length === 0) {
+    md += syncSummary.reason ? `*Observação:* ${syncSummary.reason}\n` : '*Nenhum link para sincronizar no contexto atual.*\n';
+    return md;
+  }
+
+  md += '| Chave Jira | Tipo | Referência | Status |\n';
+  md += '| :--- | :--- | :--- | :--- |\n';
+  for (const r of results) {
+    const icon = r.status === 'SUCCESS' ? '✅' : '❌';
+    md += `| \`${r.key}\` | \`${r.type}\` | \`${r.ref}\` | ${icon} \`${r.status}\` |\n`;
+  }
+
+  return md;
+}
+
+/**
+ * Audita o resultado da sincronização de links emitindo relatório OASIS SARIF v2.1.0.
+ * @param {object} [syncSummary={}] 
+ * @returns {object} SARIF v2.1.0 JSON object
+ */
+function auditSyncToSarif(syncSummary = {}) {
+  const rules = [
+    {
+      id: 'RULE-SYNC-001',
+      name: 'JiraIssueKeyMissing',
+      severity: 'WARNING',
+      message: 'Nenhuma chave de issue Jira identificada no contexto atual do Git (Regra 11).',
+      remediation: 'Incluir a chave Jira no nome da branch ou na mensagem do commit: [<TICKET>] - <Ação em português>.',
+      cwe: 'CWE-1059'
+    },
+    {
+      id: 'RULE-SYNC-002',
+      name: 'RemoteLinkSyncFailed',
+      severity: 'ERROR',
+      message: 'Falha ao sincronizar Remote Link no card do Jira.',
+      remediation: 'Verifique credenciais Atlassian (Regra 15), permissões de projeto ou validade da chave Jira.',
+      cwe: 'CWE-287'
+    },
+    {
+      id: 'RULE-SYNC-003',
+      name: 'RemoteLinkSyncSuccess',
+      severity: 'NOTE',
+      message: 'Remote Link sincronizado com sucesso no card do Jira.',
+      remediation: 'Nenhuma ação necessária. Vínculo ativo e registrado.',
+      cwe: 'CWE-Unknown'
+    }
+  ];
+
+  const findings = [];
+  const keys = syncSummary.keys || [];
+  const results = syncSummary.results || [];
+
+  if (keys.length === 0) {
+    findings.push({
+      ruleId: 'RULE-SYNC-001',
+      severity: 'WARNING',
+      message: syncSummary.reason || 'Nenhuma chave Jira identificada no contexto atual.',
+      filename: '.git',
+      line: 1,
+      column: 1
+    });
+  }
+
+  for (const r of results) {
+    if (r.status !== 'SUCCESS') {
+      findings.push({
+        ruleId: 'RULE-SYNC-002',
+        severity: 'ERROR',
+        message: `Falha ao registrar remote link (${r.type}: ${r.ref}) para a chave ${r.key}.`,
+        filename: '.git',
+        line: 1,
+        column: 1
+      });
+    }
+  }
+
+  return createSarifReport({
+    toolName: 'agent-master-atlassian-sync-action',
+    toolVersion: '5.1.0',
+    rules,
+    findings,
+    properties: {
+      category: 'Governance & Remote Links Sync',
+      keysCount: keys.length,
+      linksCount: results.length
+    }
+  });
+}
+
+/**
+ * Classe Canônica AtlassianSyncAction.
+ * Fornece API orientada a objetos para orquestração da sincronização Git-Jira.
+ */
+class AtlassianSyncAction {
+  constructor(options = {}) {
+    this.options = Object.freeze({
+      targetDir: options.targetDir || process.cwd(),
+      timeout: options.timeout || 30000,
+      ...options
+    });
+    this.atlassianClient = new AtlassianClient(this.options.targetDir, { timeout: this.options.timeout });
+  }
+
+  getAuth() {
+    return this.atlassianClient.getCredentials().authBase64;
+  }
+
+  extractKeys(text) {
+    return extractIssueKeys(text);
+  }
+
+  extractPr(text) {
+    return extractPrNumber(text);
+  }
+
+  formatPayload(url, title, type, globalId, summary) {
+    return formatRemoteLinkPayload(url, title, type, globalId, summary);
+  }
+
+  async linkUrl(issueKey, url, title, type = 'commit', globalId = null, summary = null) {
+    return linkUrlToJira(issueKey, url, title, type, null, globalId, summary);
+  }
+
+  async linkConfluence(issueKey, pageUrl, pageTitle, summary = null) {
+    return linkConfluencePageToJira(issueKey, pageUrl, pageTitle, summary);
+  }
+
+  async backfill(limit = 30) {
+    return backfillHistory(limit);
+  }
+
+  async syncCurrentContext() {
+    return syncCurrentContext(this.options.targetDir);
+  }
+
+  formatReport(syncResults = {}) {
+    return formatReport(syncResults);
+  }
+
+  auditToSarif(syncResults = {}) {
+    return auditSyncToSarif(syncResults);
+  }
+
+  // Métodos Estáticos Canônicos
+  static extractIssueKeys(text) {
+    return extractIssueKeys(text);
+  }
+
+  static extractPrNumber(text) {
+    return extractPrNumber(text);
+  }
+
+  static formatRemoteLinkPayload(url, title, type, globalId, summary) {
+    return formatRemoteLinkPayload(url, title, type, globalId, summary);
+  }
+
+  static async linkUrlToJira(issueKey, url, title, type, authOverride, globalId, summary) {
+    return linkUrlToJira(issueKey, url, title, type, authOverride, globalId, summary);
+  }
+
+  static async linkConfluencePageToJira(issueKey, pageUrl, pageTitle, summary) {
+    return linkConfluencePageToJira(issueKey, pageUrl, pageTitle, summary);
+  }
+
+  static async backfillHistory(limit) {
+    return backfillHistory(limit);
+  }
+
+  static async syncCurrentContext(targetDir) {
+    return syncCurrentContext(targetDir);
+  }
+
+  static formatReport(syncResults) {
+    return formatReport(syncResults);
+  }
+
+  static auditToSarif(syncResults) {
+    return auditSyncToSarif(syncResults);
+  }
+}
+
+/**
+ * Ponto de entrada CLI para execução no GitHub Actions ou terminal local.
+ */
+async function runCli() {
+  const isCI = process.env.GITHUB_ACTIONS === 'true';
+
+  // Validação Compulsória de Requisitos (Regra 15)
+  // Em CI, a ausência de secrets é ERRO CRÍTICO para impedir perda silenciosa
+  const validation = validateRule15({ failFast: isCI, requireGitHub: false, requireAtlassian: true });
+  if (!validation.valid) {
+    console.error(`[Atlassian Sync] Falha de validação da Regra 15:\n  ${validation.missing.join(', ')}`);
+    console.error(`  Remediação: ${validation.remediation.join('\n  ')}`);
+    if (isCI) {
+      process.exit(1);
+    }
+    return;
+  }
+
+  const args = process.argv.slice(2);
+  if (args.includes('--retroactive') || args.includes('-r')) {
+    const limitIdx = args.findIndex(a => a === '--retroactive' || a === '-r');
+    const limitVal = parseInt(args[limitIdx + 1], 10) || 30;
+    await backfillHistory(limitVal);
+    return;
+  }
+
+  const syncOutcome = await syncCurrentContext();
+  if (!syncOutcome.synced) {
+    console.log(`[Atlassian Sync] ${syncOutcome.reason}`);
+    return;
+  }
+
+  console.log(`[Atlassian Sync] Chaves Jira identificadas: ${syncOutcome.keys.join(', ')}`);
+  for (const r of syncOutcome.results) {
+    console.log(`[Atlassian Sync] ${r.type.toUpperCase()} ${r.ref} vinculado a ${r.key}: ${r.status}`);
+  }
+}
+
+if (require.main === module) {
+  runCli().catch(err => {
+    console.error('[Atlassian Sync] Erro fatal na execução:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  AtlassianSyncAction,
+  getAuth,
+  extractIssueKeys,
+  extractPrNumber,
+  formatRemoteLinkPayload,
+  linkUrlToJira,
+  linkConfluencePageToJira,
+  backfillHistory,
+  syncCurrentContext,
+  formatReport,
+  auditSyncToSarif,
+  runCli
+};