@theihtisham/ai-release-notes 1.0.0

package/action.yml

@@ -0,0 +1,113 @@
+name: 'AI Release Notes'
+description: 'Auto-generate beautiful release notes from commits, PRs, and diffs using AI'
+author: 'your-username'
+
+inputs:
+  github-token:
+    description: 'GitHub token for API access'
+    required: true
+  api-key:
+    description: 'OpenAI-compatible API key (optional — works without AI too)'
+    required: false
+  api-base:
+    description: 'API endpoint (supports any OpenAI-compatible API)'
+    required: false
+    default: 'https://api.openai.com/v1'
+  model:
+    description: 'AI model to use for natural language generation'
+    required: false
+    default: 'gpt-4o-mini'
+  template:
+    description: 'Release notes template: default, minimal, detailed, enterprise, fun, or custom path'
+    required: false
+    default: 'default'
+  commit-mode:
+    description: 'How to collect changes: commits, pull-requests, or auto'
+    required: false
+    default: 'auto'
+  version-from:
+    description: 'How to determine version: tag, package-json, or manual'
+    required: false
+    default: 'tag'
+  version:
+    description: 'Manual version (when version-from is manual)'
+    required: false
+  previous-tag:
+    description: 'Previous release tag (auto-detected if omitted)'
+    required: false
+  include-breaking:
+    description: 'Include BREAKING CHANGE section'
+    required: false
+    default: 'true'
+  include-contributors:
+    description: 'Include contributor thanks section'
+    required: false
+    default: 'true'
+  include-diff-stats:
+    description: 'Include file change statistics'
+    required: false
+    default: 'true'
+  include-screenshots:
+    description: 'Detect and include screenshot links from PRs'
+    required: false
+    default: 'true'
+  categories:
+    description: 'Custom categories as JSON array: [{"label":"Features","patterns":["feat","feature"]}]'
+    required: false
+    default: 'auto'
+  max-commits:
+    description: 'Maximum commits to analyze (prevents token overflow)'
+    required: false
+    default: '200'
+  language:
+    description: 'Output language: en, es, fr, de, ja, ko, zh, pt, ru'
+    required: false
+    default: 'en'
+  dry-run:
+    description: 'Generate notes but do not create release/post'
+    required: false
+    default: 'false'
+  slack-webhook:
+    description: 'Slack webhook URL (posts release notes to Slack)'
+    required: false
+  discord-webhook:
+    description: 'Discord webhook URL (posts release notes to Discord)'
+    required: false
+  twitter-consumer-key:
+    description: 'Twitter API consumer key (posts release tweet)'
+    required: false
+  twitter-consumer-secret:
+    description: 'Twitter API consumer secret'
+    required: false
+  twitter-access-token:
+    description: 'Twitter API access token'
+    required: false
+  twitter-access-secret:
+    description: 'Twitter API access token secret'
+    required: false
+  update-changelog:
+    description: 'Automatically update CHANGELOG.md'
+    required: false
+    default: 'false'
+  changelog-path:
+    description: 'Path to changelog file'
+    required: false
+    default: 'CHANGELOG.md'
+
+outputs:
+  release-notes:
+    description: 'Generated release notes markdown'
+  release-url:
+    description: 'URL of the created GitHub Release'
+  version:
+    description: 'The version number used'
+  summary:
+    description: 'One-line summary of the release'
+
+runs:
+  using: 'node20'
+  main: 'dist/index.js'
+
+branding:
+  icon: 'file-text'
+  color: 'green'

package/index.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const core = require('@actions/core');
+const logger = require('./src/logger');
+const { createConfig } = require('./src/config');
+const { generate } = require('./src/generator');
+
+/**
+ * Entry point for the GitHub Action.
+ */
+async function run() {
+  try {
+    logger.info('AI Release Notes action started');
+
+    // Collect all inputs
+    const inputs = {
+      'github-token': core.getInput('github-token', { required: true }),
+      'api-key': core.getInput('api-key') || '',
+      'api-base': core.getInput('api-base') || 'https://api.openai.com/v1',
+      model: core.getInput('model') || 'gpt-4o-mini',
+      template: core.getInput('template') || 'default',
+      'commit-mode': core.getInput('commit-mode') || 'auto',
+      'version-from': core.getInput('version-from') || 'tag',
+      version: core.getInput('version') || '',
+      'previous-tag': core.getInput('previous-tag') || '',
+      'include-breaking': core.getInput('include-breaking') || 'true',
+      'include-contributors': core.getInput('include-contributors') || 'true',
+      'include-diff-stats': core.getInput('include-diff-stats') || 'true',
+      'include-screenshots': core.getInput('include-screenshots') || 'true',
+      categories: core.getInput('categories') || 'auto',
+      'max-commits': core.getInput('max-commits') || '200',
+      language: core.getInput('language') || 'en',
+      'dry-run': core.getInput('dry-run') || 'false',
+      'slack-webhook': core.getInput('slack-webhook') || '',
+      'discord-webhook': core.getInput('discord-webhook') || '',
+      'twitter-consumer-key': core.getInput('twitter-consumer-key') || '',
+      'twitter-consumer-secret': core.getInput('twitter-consumer-secret') || '',
+      'twitter-access-token': core.getInput('twitter-access-token') || '',
+      'twitter-access-secret': core.getInput('twitter-access-secret') || '',
+      'update-changelog': core.getInput('update-changelog') || 'false',
+      'changelog-path': core.getInput('changelog-path') || 'CHANGELOG.md',
+    };
+
+    // Create validated config
+    const config = createConfig(inputs);
+
+    // Run the generator
+    const result = await generate(config);
+
+    // Set outputs
+    core.setOutput('release-notes', result.notes);
+    core.setOutput('release-url', result.url || '');
+    core.setOutput('version', result.version || '');
+    core.setOutput('summary', result.summary || '');
+
+    // Also set the release notes as the job summary
+    if (result.notes) {
+      await core.summary.addRaw(result.notes).write();
+    }
+
+    logger.info('AI Release Notes action completed successfully');
+  } catch (err) {
+    logger.error('Action failed', err);
+    core.setFailed(`AI Release Notes failed: ${err.message}`);
+  }
+}
+
+// Run if called directly (not in test)
+if (require.main === module) {
+  run();
+}
+
+module.exports = { run };

package/jest.config.js

@@ -0,0 +1,10 @@
+'use strict';
+
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.js'],
+  collectCoverageFrom: ['src/**/*.js', '!src/logger.js'],
+  coverageThreshold: {
+    global: { branches: 20, functions: 20, lines: 20, statements: 20 },
+  },
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@theihtisham/ai-release-notes",
+  "version": "1.0.0",
+  "description": "Auto-generate beautiful release notes from commits, PRs, and diffs using AI",
+  "main": "index.js",
+  "scripts": {
+    "build": "ncc build index.js -o dist --source-map",
+    "test": "jest --coverage",
+    "lint": "eslint src/",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@actions/core": "^1.10.1",
+    "@actions/github": "^6.0.0",
+    "openai": "^4.67.0",
+    "minimatch": "^9.0.4",
+    "twitter-api-v2": "^1.16.0",
+    "node-fetch": "^3.3.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "@vercel/ncc": "^0.38.3",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.0"
+  },
+  "keywords": [
+    "github-action",
+    "release-notes",
+    "ai",
+    "changelog",
+    "automation"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theihtisham/ai-release-notes.git"
+  }
+}

package/src/ai-writer.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const logger = require('./logger');
+const { getSystemPrompt, getUserPrompt } = require('./prompts');
+
+/**
+ * Generate release notes using AI (OpenAI-compatible API).
+ * Falls back to template-based generation if AI fails or no API key.
+ *
+ * @param {Object} analysis - Commit analysis results
+ * @param {Object} diffSummary - Diff analysis results
+ * @param {string} version - Current version
+ * @param {Object} config - Configuration object
+ * @returns {string} Generated release notes markdown
+ */
+async function generateReleaseNotes(analysis, diffSummary, version, config) {
+  if (!config.hasAI || !config.apiKey) {
+    logger.info('No API key provided — using template-based generation');
+    return null;
+  }
+
+  try {
+    logger.info(`Generating AI release notes with model ${config.model}`);
+
+    // Use dynamic import for OpenAI (ESM module)
+    let openaiModule;
+    try {
+      openaiModule = await import('openai');
+    } catch (importErr) {
+      logger.warn(`Failed to import OpenAI module: ${importErr.message}`);
+      return null;
+    }
+
+    const OpenAI = openaiModule.default || openaiModule.OpenAI;
+
+    const client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.apiBase,
+    });
+
+    const systemPrompt = getSystemPrompt(config);
+    const userPrompt = getUserPrompt(analysis, diffSummary, version, config);
+
+    logger.debug('Sending request to AI API...');
+
+    const response = await client.chat.completions.create({
+      model: config.model,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+      ],
+      temperature: 0.3,
+      max_tokens: 4000,
+    });
+
+    if (!response || !response.choices || response.choices.length === 0) {
+      logger.warn('AI returned empty response — falling back to template');
+      return null;
+    }
+
+    const content = response.choices[0].message.content;
+
+    if (!content || content.trim().length === 0) {
+      logger.warn('AI returned empty content — falling back to template');
+      return null;
+    }
+
+    // Validate: must be valid markdown with some content
+    if (!validateAIResponse(content)) {
+      logger.warn('AI response validation failed — falling back to template');
+      return null;
+    }
+
+    logger.info('AI release notes generated successfully');
+    return content;
+  } catch (err) {
+    logger.error('AI generation failed — falling back to template', err);
+    return null;
+  }
+}
+
+/**
+ * Validate AI response content.
+ * Checks that the response is non-empty markdown with at least one section.
+ */
+function validateAIResponse(content) {
+  if (!content || typeof content !== 'string') {
+    return false;
+  }
+
+  // Must have at least 50 characters of content
+  if (content.trim().length < 50) {
+    return false;
+  }
+
+  // Must contain at least one markdown element (header, bullet, or link)
+  const hasMarkdown = /(^#{1,6}\s|^- |\*\s|[^!]\[.*\]\(.*\))/.test(content);
+  if (!hasMarkdown) {
+    return false;
+  }
+
+  return true;
+}
+
+module.exports = {
+  generateReleaseNotes,
+  validateAIResponse,
+};

package/src/analyzer.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const { CONVENTIONAL_COMMIT_REGEX, BREAKING_CHANGE_REGEX } = require('./constants');
+const { categorizeCommits, deduplicateChanges } = require('./categorizer');
+const { getContributors } = require('./contributor');
+const logger = require('./logger');
+
+/**
+ * Analyze commits and produce a structured analysis.
+ * @param {Array} commits - Array of commit objects from GitHub API
+ * @param {Object} config - Configuration object
+ * @returns {Object} Structured analysis with categories, breaking changes, contributors, scopes, stats
+ */
+function analyzeCommits(commits, config) {
+  logger.info(`Analyzing ${commits ? commits.length : 0} commits`);
+
+  if (!commits || commits.length === 0) {
+    return {
+      categories: {},
+      breaking: [],
+      contributors: [],
+      scopes: {},
+      stats: {
+        total_commits: 0,
+        total_prs: 0,
+        total_files_changed: 0,
+        additions: 0,
+        deletions: 0,
+      },
+      linkedIssues: [],
+    };
+  }
+
+  const parsedCommits = commits.map(parseCommit).filter(Boolean);
+  const categories = categorizeCommits(parsedCommits, config.categories);
+  const dedupedCategories = deduplicateChanges(categories);
+  const breaking = extractBreakingChanges(parsedCommits);
+  const contributors = getContributors(commits, null);
+  const scopes = extractScopes(parsedCommits);
+  const stats = computeStats(parsedCommits);
+  const linkedIssues = extractLinkedIssues(parsedCommits);
+
+  logger.info(`Analysis complete: ${stats.total_commits} commits, ${Object.keys(dedupedCategories).length} categories, ${breaking.length} breaking changes`);
+
+  return {
+    categories: dedupedCategories,
+    breaking: breaking,
+    contributors: contributors,
+    scopes: scopes,
+    stats: stats,
+    linkedIssues: linkedIssues,
+  };
+}
+
+/**
+ * Parse a single commit into structured data.
+ */
+function parseCommit(commit) {
+  try {
+    const message = commit.message || (commit.commit && commit.commit.message) || '';
+    const match = message.match(CONVENTIONAL_COMMIT_REGEX);
+
+    if (!match) {
+      return {
+        ...commit,
+        _type: 'other',
+        _scope: '',
+        _description: message,
+        _breaking: false,
+        _pr: null,
+        _body: '',
+      };
+    }
+
+    const type = match[1].toLowerCase();
+    const scope = match[3] || '';
+    const breakingBang = !!match[4];
+    const description = match[5] || '';
+
+    // Extract body (everything after first line)
+    const lines = message.split('\n');
+    const body = lines.slice(1).join('\n').trim();
+
+    // Check for BREAKING CHANGE in body
+    const breakingMatch = body.match(BREAKING_CHANGE_REGEX);
+    const hasBreakingFooter = !!breakingMatch;
+    const breakingDescription = breakingMatch ? breakingMatch[1] : '';
+
+    return {
+      ...commit,
+      _type: type,
+      _scope: scope,
+      _description: description,
+      _breaking: breakingBang || hasBreakingFooter,
+      _breakingDescription: breakingDescription,
+      _pr: extractPRNumber(message),
+      _body: body,
+    };
+  } catch (err) {
+    logger.debug(`Failed to parse commit: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Extract PR number from commit message.
+ */
+function extractPRNumber(message) {
+  const match = message.match(/\(#(\d+)\)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Extract breaking changes from parsed commits.
+ */
+function extractBreakingChanges(parsedCommits) {
+  const breaking = [];
+
+  for (const commit of parsedCommits) {
+    if (!commit) continue;
+    if (commit._breaking) {
+      breaking.push({
+        description: commit._breakingDescription || commit._description,
+        commit: commit.sha || '',
+        scope: commit._scope || '',
+        type: commit._type || '',
+        pr: commit._pr,
+        migration_guide: extractMigrationGuide(commit._body),
+      });
+    }
+  }
+
+  return breaking;
+}
+
+/**
+ * Try to extract migration guide from commit body.
+ */
+function extractMigrationGuide(body) {
+  if (!body) return '';
+  // Look for migration guidance patterns
+  const patterns = [
+    /Migration Guide:\s*([\s\S]*?)(?=\n\n|\n##|$)/i,
+    /How to migrate:\s*([\s\S]*?)(?=\n\n|\n##|$)/i,
+    /To migrate[\s\S]*?:\s*([\s\S]*?)(?=\n\n|\n##|$)/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = body.match(pattern);
+    if (match) return match[1].trim();
+  }
+
+  return '';
+}
+
+/**
+ * Extract and count scopes from parsed commits.
+ */
+function extractScopes(parsedCommits) {
+  const scopes = {};
+  for (const commit of parsedCommits) {
+    if (!commit) continue;
+    const scope = commit._scope;
+    if (scope) {
+      scopes[scope] = (scopes[scope] || 0) + 1;
+    }
+  }
+  return scopes;
+}
+
+/**
+ * Compute aggregate stats from parsed commits.
+ */
+function computeStats(parsedCommits) {
+  let totalPrs = 0;
+  let totalFilesChanged = 0;
+  let additions = 0;
+  let deletions = 0;
+
+  for (const commit of parsedCommits) {
+    if (!commit) continue;
+    if (commit._pr) totalPrs++;
+    if (commit.files) totalFilesChanged += commit.files.length || commit.files;
+    if (commit.stats) {
+      additions += commit.stats.additions || 0;
+      deletions += commit.stats.deletions || 0;
+    }
+  }
+
+  return {
+    total_commits: parsedCommits.filter(Boolean).length,
+    total_prs: totalPrs,
+    total_files_changed: totalFilesChanged,
+    additions: additions,
+    deletions: deletions,
+  };
+}
+
+/**
+ * Extract linked issue numbers from commit messages.
+ */
+function extractLinkedIssues(parsedCommits) {
+  const issues = [];
+  const seen = new Set();
+
+  for (const commit of parsedCommits) {
+    if (!commit) continue;
+    const message = commit.message || (commit.commit && commit.commit.message) || '';
+    // Match #123 patterns
+    const issueMatches = message.matchAll(/#(\d+)/g);
+    for (const match of issueMatches) {
+      const num = parseInt(match[1], 10);
+      // Skip if it's a PR number (detected by (#123) pattern)
+      if (commit._pr === num) continue;
+      if (!seen.has(num)) {
+        seen.add(num);
+        issues.push({ number: num });
+      }
+    }
+  }
+
+  return issues;
+}
+
+module.exports = {
+  analyzeCommits,
+  parseCommit,
+  extractBreakingChanges,
+  extractScopes,
+  computeStats,
+  extractLinkedIssues,
+};