@theihtisham/ai-release-notes 1.0.0

package/src/formatters/index.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { OUTPUT_FORMATS, isValidFormat } = require('./types');
+const { MarkdownFormatter } = require('./markdown');
+const { HTMLFormatter } = require('./html');
+const { SlackFormatter } = require('./slack');
+const { DiscordFormatter } = require('./discord');
+const { TwitterFormatter } = require('./twitter');
+
+/**
+ * Formatter factory. Returns the appropriate formatter for a given output format.
+ * @param {string} format - Output format identifier ('markdown', 'html', 'slack', 'discord', 'twitter')
+ * @returns {Object} Formatter instance with name, format, and format() method
+ * @throws {Error} If format is not recognized
+ */
+function getFormatter(format) {
+  switch (format) {
+    case 'markdown':
+      return new MarkdownFormatter();
+    case 'html':
+      return new HTMLFormatter();
+    case 'slack':
+      return new SlackFormatter();
+    case 'discord':
+      return new DiscordFormatter();
+    case 'twitter':
+      return new TwitterFormatter();
+    default:
+      throw new Error(`Unknown output format: "${format}". Valid formats: ${OUTPUT_FORMATS.join(', ')}`);
+  }
+}
+
+module.exports = {
+  getFormatter,
+  OUTPUT_FORMATS,
+  isValidFormat,
+  MarkdownFormatter,
+  HTMLFormatter,
+  SlackFormatter,
+  DiscordFormatter,
+  TwitterFormatter,
+};

package/src/formatters/markdown.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { formatDiffStats } = require('../diff-analyzer');
+
+/**
+ * GitHub-flavored Markdown formatter.
+ * Produces rich markdown with emojis, collapsible sections, code blocks,
+ * and contributor acknowledgments.
+ */
+class MarkdownFormatter {
+  constructor() {
+    this.name = 'Markdown';
+    this.formatName = 'markdown';
+  }
+
+  /**
+   * Format release data as GitHub-flavored markdown.
+   * @param {Object} data - ReleaseData object
+   * @returns {string} Formatted markdown string
+   */
+  format(data) {
+    const lines = [];
+
+    // Title and summary
+    lines.push(`## What's Changed in v${data.version}`);
+    lines.push('');
+    lines.push(`> ${data.summary || `Release v${data.version}`}`);
+    lines.push('');
+
+    // Breaking changes (prominent, red alert)
+    if (data.breaking && data.breaking.length > 0) {
+      lines.push('### :rotating_light: Breaking Changes');
+      lines.push('');
+      lines.push('<details>');
+      lines.push('<summary><strong>Click to view breaking changes and migration guide</strong></summary>');
+      lines.push('');
+      for (const bc of data.breaking) {
+        lines.push(`- **${bc.description}**`);
+        if (bc.scope) {
+          lines.push(`  - Scope: \`${bc.scope}\``);
+        }
+        if (bc.migration_guide) {
+          lines.push(`  - **Migration**: ${bc.migration_guide}`);
+        }
+        if (bc.pr) {
+          lines.push(`  - PR: [#${bc.pr}](${data.repoUrl}/pull/${bc.pr})`);
+        }
+      }
+      lines.push('');
+      lines.push('</details>');
+      lines.push('');
+    }
+
+    // Categorized changes
+    if (data.categories && Object.keys(data.categories).length > 0) {
+      for (const [category, changes] of Object.entries(data.categories)) {
+        lines.push(`### ${category}`);
+        lines.push('');
+        for (const change of changes) {
+          let line = `- ${change.description}`;
+          if (change.scope) {
+            line += ` [\`${change.scope}\`]`;
+          }
+          if (change.pr) {
+            line += ` ([#${change.pr}](${data.repoUrl}/pull/${change.pr}))`;
+          }
+          if (change.author) {
+            line += ` by @${change.author}`;
+          }
+          lines.push(line);
+        }
+        lines.push('');
+      }
+    }
+
+    // Diff statistics (collapsible)
+    if (data.diffSummary && data.diffSummary.files_changed > 0) {
+      lines.push('<details>');
+      lines.push('<summary>:bar_chart: Diff Statistics</summary>');
+      lines.push('');
+      lines.push(formatDiffStats(data.diffSummary));
+      lines.push('');
+      lines.push('</details>');
+      lines.push('');
+    }
+
+    // Linked issues (collapsible)
+    if (data.linkedIssues && data.linkedIssues.length > 0) {
+      lines.push('<details>');
+      lines.push(`<summary>:link: Linked Issues (${data.linkedIssues.length})</summary>`);
+      lines.push('');
+      for (const issue of data.linkedIssues) {
+        lines.push(`- [#${issue.number}](${data.repoUrl}/issues/${issue.number})`);
+      }
+      lines.push('');
+      lines.push('</details>');
+      lines.push('');
+    }
+
+    // Contributors
+    if (data.contributors && data.contributors.length > 0) {
+      lines.push('### :busts_in_silhouette: Contributors');
+      lines.push('');
+      const logins = data.contributors.map(c => {
+        const badge = c.is_first_time ? ' :tada:' : '';
+        return `- @${c.login} (${c.commits_count} commit${c.commits_count !== 1 ? 's' : ''})${badge}`;
+      });
+      lines.push(logins.join('\n'));
+      lines.push('');
+    }
+
+    // Full changelog link
+    if (data.previousVersion) {
+      lines.push(`**Full Changelog**: ${data.repoUrl}/compare/v${data.previousVersion}...v${data.version}`);
+    } else {
+      lines.push(`**Full Changelog**: ${data.repoUrl}/releases/tag/v${data.version}`);
+    }
+
+    return lines.join('\n');
+  }
+}
+
+module.exports = { MarkdownFormatter };

package/src/formatters/slack.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * Slack Block Kit formatter.
+ * Produces JSON with Slack Block Kit sections, dividers, fields,
+ * context blocks, and mention support.
+ */
+class SlackFormatter {
+  constructor() {
+    this.name = 'Slack';
+    this.formatName = 'slack';
+  }
+
+  /**
+   * Format release data as Slack Block Kit JSON string.
+   * @param {Object} data - ReleaseData object
+   * @returns {string} JSON string of Slack Block Kit payload
+   */
+  format(data) {
+    const blocks = [];
+
+    // Header block
+    blocks.push({
+      type: 'header',
+      text: {
+        type: 'plain_text',
+        text: `Release v${data.version}`,
+        emoji: true,
+      },
+    });
+
+    // Summary section
+    blocks.push({
+      type: 'section',
+      text: {
+        type: 'mrkdwn',
+        text: `:rocket: *${this._escapeSlack(data.summary || `Release v${data.version}`)}*`,
+      },
+    });
+
+    // Date context
+    blocks.push({
+      type: 'context',
+      elements: [
+        {
+          type: 'mrkdwn',
+          text: `:calendar: ${data.date}`,
+        },
+      ],
+    });
+
+    // Breaking changes (alert)
+    if (data.breaking && data.breaking.length > 0) {
+      blocks.push({ type: 'divider' });
+      blocks.push({
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: `:rotating_light: *Breaking Changes*`,
+        },
+      });
+
+      const breakingText = data.breaking.map(bc => {
+        let line = `> *${this._escapeSlack(bc.description)}*`;
+        if (bc.scope) line += ` \`${this._escapeSlack(bc.scope)}\``;
+        if (bc.migration_guide) line += `\n> _Migration: ${this._escapeSlack(bc.migration_guide)}_`;
+        return line;
+      }).join('\n');
+
+      blocks.push({
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: breakingText,
+        },
+      });
+    }
+
+    // Categorized changes
+    if (data.categories) {
+      for (const [category, changes] of Object.entries(data.categories)) {
+        blocks.push({ type: 'divider' });
+
+        // Category header
+        blocks.push({
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text: `*${this._escapeSlack(category)}*`,
+          },
+        });
+
+        // Changes as fields (max 10 per block, max 5 visible)
+        const fields = [];
+        for (const change of changes.slice(0, 10)) {
+          let text = this._escapeSlack(change.description);
+          if (change.pr) text += ` <${data.repoUrl}/pull/${change.pr}|#${change.pr}>`;
+          if (change.author) text += ` _@${change.author}_`;
+          fields.push({
+            type: 'mrkdwn',
+            text: text.length > 200 ? text.substring(0, 197) + '...' : text,
+          });
+        }
+
+        // Slack supports max 10 fields per block
+        for (let i = 0; i < fields.length; i += 10) {
+          blocks.push({
+            type: 'section',
+            fields: fields.slice(i, i + 10),
+          });
+        }
+      }
+    }
+
+    // Contributors context
+    if (data.contributors && data.contributors.length > 0) {
+      blocks.push({ type: 'divider' });
+      const names = data.contributors.slice(0, 8).map(c => {
+        const suffix = c.is_first_time ? ' :tada:' : '';
+        return `@${c.login}${suffix}`;
+      }).join(', ');
+      const more = data.contributors.length > 8 ? ` and ${data.contributors.length - 8} more` : '';
+
+      blocks.push({
+        type: 'context',
+        elements: [
+          {
+            type: 'mrkdwn',
+            text: `:busts_in_silhouette: Contributors: ${names}${more}`,
+          },
+        ],
+      });
+    }
+
+    // Full changelog button
+    blocks.push({ type: 'divider' });
+    const actions = [];
+    if (data.previousVersion) {
+      actions.push({
+        type: 'button',
+        text: {
+          type: 'plain_text',
+          text: 'View Full Changelog',
+        },
+        url: `${data.repoUrl}/compare/v${data.previousVersion}...v${data.version}`,
+      });
+    }
+    actions.push({
+      type: 'button',
+      text: {
+        type: 'plain_text',
+        text: 'View Repository',
+      },
+      url: data.repoUrl,
+    });
+
+    blocks.push({
+      type: 'actions',
+      elements: actions,
+    });
+
+    return JSON.stringify({ blocks }, null, 2);
+  }
+
+  /**
+   * Escape Slack mrkdwn special characters.
+   * @param {string} str
+   * @returns {string}
+   */
+  _escapeSlack(str) {
+    if (!str) return '';
+    return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+}
+
+module.exports = { SlackFormatter };

package/src/formatters/twitter.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * Twitter/X thread formatter.
+ * Breaks release notes into a tweet thread with 280-character limit per tweet,
+ * numbered tweets (1/N, 2/N, etc.), and hashtag suggestions.
+ */
+class TwitterFormatter {
+  constructor() {
+    this.name = 'Twitter';
+    this.formatName = 'twitter';
+    this.MAX_TWEET_LENGTH = 280;
+  }
+
+  /**
+   * Format release data as a Twitter thread (array of tweet objects).
+   * @param {Object} data - ReleaseData object
+   * @returns {string} JSON string of tweet array
+   */
+  format(data) {
+    const tweets = [];
+
+    // Tweet 1: Announcement
+    let announcement = `v${data.version} is here! `;
+    if (data.summary && data.summary.length < 150) {
+      announcement += data.summary;
+    } else {
+      announcement += this._shortSummary(data);
+    }
+    announcement = this._trimToLength(announcement, this.MAX_TWEET_LENGTH);
+    tweets.push(announcement);
+
+    // Tweet 2: Features (if any)
+    const featureCategories = this._getCategoriesByType(data, 'feature');
+    if (featureCategories.length > 0) {
+      const featureTweets = this._formatCategoryThread(
+        featureCategories,
+        ':rocket: New in v' + data.version + ':'
+      );
+      tweets.push(...featureTweets);
+    }
+
+    // Tweet: Bug fixes (if any)
+    const fixCategories = this._getCategoriesByType(data, 'fix');
+    if (fixCategories.length > 0) {
+      const fixTweets = this._formatCategoryThread(
+        fixCategories,
+        ':wrench: Bug fixes in v' + data.version + ':'
+      );
+      tweets.push(...fixTweets);
+    }
+
+    // Tweet: Breaking changes (if any)
+    if (data.breaking && data.breaking.length > 0) {
+      const breakingTexts = [];
+      for (const bc of data.breaking) {
+        let text = `- ${bc.description}`;
+        if (bc.migration_guide) {
+          text += ` | Migration: ${bc.migration_guide}`;
+        }
+        breakingTexts.push(text);
+      }
+      const breakingTweets = this._splitIntoTweets(
+        breakingTexts,
+        ':rotating_light: BREAKING CHANGES in v' + data.version + ':'
+      );
+      tweets.push(...breakingTweets);
+    }
+
+    // Tweet: Other categories
+    const otherCategories = this._getOtherCategories(data);
+    for (const [cat, changes] of otherCategories) {
+      const items = changes.map(c => `- ${c.description}`);
+      const catTweets = this._splitIntoTweets(items, `${cat}:`);
+      tweets.push(...catTweets);
+    }
+
+    // Tweet: Contributors
+    if (data.contributors && data.contributors.length > 0) {
+      const names = data.contributors.slice(0, 10).map(c => `@${c.login}`).join(', ');
+      const more = data.contributors.length > 10 ? ` +${data.contributors.length - 10} more` : '';
+      const firstTimers = data.contributors.filter(c => c.is_first_time);
+      let contributorTweet = `Contributors: ${names}${more}`;
+      if (firstTimers.length > 0) {
+        contributorTweet += `\nFirst-time: ${firstTimers.map(c => `@${c.login}`).join(', ')}`;
+      }
+      tweets.push(this._trimToLength(contributorTweet, this.MAX_TWEET_LENGTH));
+    }
+
+    // Tweet: Link + hashtags
+    let linkTweet = '';
+    if (data.previousVersion) {
+      linkTweet = `Full changelog: ${data.repoUrl}/compare/v${data.previousVersion}...v${data.version}`;
+    } else {
+      linkTweet = `${data.repoUrl}`;
+    }
+    const hashtags = this._suggestHashtags(data);
+    linkTweet += `\n\n${hashtags}`;
+    tweets.push(this._trimToLength(linkTweet, this.MAX_TWEET_LENGTH));
+
+    // Number all tweets
+    const total = tweets.length;
+    const numbered = tweets.map((tweet, i) => {
+      const prefix = `${i + 1}/${total} `;
+      if ((prefix + tweet).length <= this.MAX_TWEET_LENGTH) {
+        return prefix + tweet;
+      }
+      // If prefix would overflow, truncate the tweet
+      return prefix + tweet.substring(0, this.MAX_TWEET_LENGTH - prefix.length);
+    });
+
+    return JSON.stringify(numbered, null, 2);
+  }
+
+  /**
+   * Get a short summary for the announcement tweet.
+   * @param {Object} data
+   * @returns {string}
+   */
+  _shortSummary(data) {
+    const parts = [];
+    if (data.categories) {
+      const catCount = Object.keys(data.categories).length;
+      if (catCount > 0) parts.push(`${catCount} categories of changes`);
+    }
+    if (data.contributors && data.contributors.length > 0) {
+      parts.push(`${data.contributors.length} contributors`);
+    }
+    if (data.breaking && data.breaking.length > 0) {
+      parts.push(`${data.breaking.length} breaking change${data.breaking.length > 1 ? 's' : ''}`);
+    }
+    return parts.length > 0 ? parts.join(', ') + '.' : 'Various improvements and fixes.';
+  }
+
+  /**
+   * Get categories that match a type keyword.
+   * @param {Object} data
+   * @param {string} type
+   * @returns {Array<{description: string}>}
+   */
+  _getCategoriesByType(data, type) {
+    const results = [];
+    if (!data.categories) return results;
+    for (const [category, changes] of Object.entries(data.categories)) {
+      if (category.toLowerCase().includes(type)) {
+        results.push(...changes);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Get categories that are not features or fixes.
+   * @param {Object} data
+   * @returns {Array}
+   */
+  _getOtherCategories(data) {
+    if (!data.categories) return [];
+    const results = [];
+    for (const [category, changes] of Object.entries(data.categories)) {
+      const lower = category.toLowerCase();
+      if (!lower.includes('feature') && !lower.includes('fix') && !lower.includes('bug')) {
+        results.push([category, changes]);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Format a set of changes as a thread with a header.
+   * @param {Array} changes
+   * @param {string} header
+   * @returns {string[]}
+   */
+  _formatCategoryThread(changes, header) {
+    const items = changes.map(c => {
+      let text = `- ${c.description}`;
+      if (c.pr) text += ` (#${c.pr})`;
+      return text;
+    });
+    return this._splitIntoTweets(items, header);
+  }
+
+  /**
+   * Split a list of text items into tweets respecting the character limit.
+   * @param {string[]} items
+   * @param {string} header
+   * @returns {string[]}
+   */
+  _splitIntoTweets(items, header) {
+    const tweets = [];
+    let current = header + '\n';
+
+    for (const item of items) {
+      if ((current + '\n' + item).length > this.MAX_TWEET_LENGTH) {
+        tweets.push(current.trim());
+        current = header + ' (cont.)\n';
+      }
+      current += item + '\n';
+    }
+
+    if (current.trim().length > header.length) {
+      tweets.push(current.trim());
+    }
+
+    return tweets;
+  }
+
+  /**
+   * Trim a string to a maximum length, respecting word boundaries.
+   * @param {string} str
+   * @param {number} max
+   * @returns {string}
+   */
+  _trimToLength(str, max) {
+    if (!str || str.length <= max) return str || '';
+    return str.substring(0, max - 1) + '...';
+  }
+
+  /**
+   * Suggest hashtags based on release content.
+   * @param {Object} data
+   * @returns {string}
+   */
+  _suggestHashtags(data) {
+    const tags = ['#Release', '#Changelog'];
+
+    if (data.breaking && data.breaking.length > 0) {
+      tags.push('#BreakingChanges');
+    }
+    if (data.categories) {
+      const catNames = Object.keys(data.categories).map(c => c.toLowerCase());
+      if (catNames.some(c => c.includes('feature'))) tags.push('#NewFeatures');
+      if (catNames.some(c => c.includes('security'))) tags.push('#Security');
+      if (catNames.some(c => c.includes('perf'))) tags.push('#Performance');
+    }
+
+    return tags.join(' ');
+  }
+}
+
+module.exports = { TwitterFormatter };

package/src/formatters/types.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * @typedef {'markdown'|'html'|'slack'|'discord'|'twitter'} OutputFormat
+ * Supported output formats for release notes.
+ */
+
+/**
+ * @typedef {Object} ReleaseData
+ * @property {string} version - Release version (e.g. "2.1.0")
+ * @property {string} previousVersion - Previous version (e.g. "2.0.0")
+ * @property {string} date - Release date (ISO format YYYY-MM-DD)
+ * @property {string} summary - One-line summary of the release
+ * @property {Object<string, Array<{description: string, type?: string, scope?: string, pr?: number|null, author?: string, breaking?: boolean}>>} categories - Categorized changes
+ * @property {Array<{description: string, scope?: string, type?: string, pr?: number|null, migration_guide?: string}>} breaking - Breaking changes
+ * @property {Array<{login: string, name?: string, commits_count: number, is_first_time?: boolean}>} contributors - Contributors
+ * @property {Object|null} diffSummary - Diff analysis summary
+ * @property {string} repoUrl - Repository URL
+ * @property {string} repoFullName - Repository full name (owner/repo)
+ * @property {Array<{number: number}>} linkedIssues - Linked issue numbers
+ */
+
+/**
+ * @typedef {Object} Formatter
+ * @property {string} name - Human-readable formatter name
+ * @property {OutputFormat} format - The format identifier
+ * @property {(data: ReleaseData) => string} format - Convert release data to formatted string
+ */
+
+/**
+ * List of all supported output formats.
+ * @type {OutputFormat[]}
+ */
+const OUTPUT_FORMATS = ['markdown', 'html', 'slack', 'discord', 'twitter'];
+
+/**
+ * Check if a format string is valid.
+ * @param {string} format - Format to validate
+ * @returns {boolean}
+ */
+function isValidFormat(format) {
+  return OUTPUT_FORMATS.includes(format);
+}
+
+module.exports = {
+  OUTPUT_FORMATS,
+  isValidFormat,
+};