@logickernel/agileflow 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logickernel/agileflow",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Automatic semantic versioning and changelog generation based on conventional commits",
   "main": "src/index.js",
   "bin": {
@@ -34,6 +34,6 @@
     "type": "git",
     "url": "git@code.logickernel.com:kernel/agileflow.git"
   },
-  "author": "",
+  "author": "Víctor H. Valle <victor.valle@logickernel.com>",
   "license": "ISC"
 }

package/src/index.js

@@ -12,9 +12,9 @@ Usage:
 
 Commands:
   <none>   Prints the current version, next version, commits, and changelog
-  push     Push a semantic version tag to the remote repository (native git)
-  gitlab   Push a semantic version tag via GitLab API (for GitLab CI)
-  github   Push a semantic version tag via GitHub API (for GitHub Actions)
+  push     Push a semantic version tag to the remote repository
+  gitlab   Create a semantic version tag via GitLab API (for GitLab CI)
+  github   Create a semantic version tag via GitHub API (for GitHub Actions)
 
 Options:
   --quiet        Only output the next version (or empty if no bump)
@@ -26,11 +26,32 @@ For more information, visit: https://code.logickernel.com/tools/agileflow
 }
 
 /**
- * Parses command line arguments.
+ * Valid options that can be passed to commands.
+ */
+const VALID_OPTIONS = ['--quiet', '--help', '-h', '--version', '-v'];
+
+/**
+ * Valid commands.
+ */
+const VALID_COMMANDS = ['push', 'gitlab', 'github'];
+
+/**
+ * Parses command line arguments and validates them.
  * @param {Array<string>} args - Command line arguments
  * @returns {{quiet: boolean}}
+ * @throws {Error} If invalid options are found
  */
 function parseArgs(args) {
+  // Check for invalid options
+  for (const arg of args) {
+    if (arg.startsWith('--') && !VALID_OPTIONS.includes(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (arg.startsWith('-') && !arg.startsWith('--') && !VALID_OPTIONS.includes(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  
   return {
     quiet: args.includes('--quiet'),
   };
@@ -38,24 +59,32 @@ function parseArgs(args) {
 
 /**
  * Displays version info to the console.
- * @param {{currentVersion: string|null, nextVersion: string|null, commits: Array, changelog: string}} info
- * @param {boolean} quiet - Only output the next version
+ * @param {{currentVersion: string|null, newVersion: string|null, commits: Array, changelog: string}} info
+ * @param {boolean} quiet - Only output the new version
  */
 function displayVersionInfo(info, quiet) {
-  const { currentVersion, nextVersion, commits, changelog } = info;
+  const { currentVersion, newVersion, commits, changelog } = info;
   
   if (quiet) {
-    if (nextVersion) {
-      console.log(nextVersion);
+    if (newVersion) {
+      console.log(newVersion);
     }
     return;
   }
   
-  console.log(`Current version: ${currentVersion || 'none'}`);
-  console.log(`Next version: ${nextVersion || 'no bump needed'}`);
-  console.log(`Commits since current version: ${commits.length}`);
+  
+  // List commits
+  console.log(`Commits since current version (${commits.length}):`);
+  for (const commit of commits) {
+    const subject = commit.message.split('\n')[0].trim();
+    const shortHash = commit.hash.substring(0, 7);
+    console.log(`  ${shortHash} ${subject}`);
+  }
+  
+  console.log(`\nCurrent version: ${currentVersion || 'none'}`);
+  console.log(`New version:     ${newVersion || 'no bump needed'}`);
   if (changelog) {
-    console.log(`\nChangelog:\n${changelog}`);
+    console.log(`\nChangelog:\n\n${changelog}`);
   }
 }
 
@@ -71,10 +100,7 @@ async function handlePushCommand(pushType, options) {
   displayVersionInfo(info, options.quiet);
   
   // Skip push if no version bump needed
-  if (!info.nextVersion) {
-    if (!options.quiet) {
-      console.log('\nNo version bump needed. Skipping tag creation.');
-    }
+  if (!info.newVersion) {
     return;
   }
   
@@ -93,22 +119,32 @@ async function handlePushCommand(pushType, options) {
   }
   
   // Create tag message from changelog
-  const tagMessage = info.changelog || info.nextVersion;
+  const tagMessage = info.changelog || info.newVersion;
   
   if (!options.quiet) {
-    console.log(`\nCreating tag ${info.nextVersion}...`);
+    console.log(`\nCreating tag ${info.newVersion}...`);
   }
   
-  await pushModule.pushTag(info.nextVersion, tagMessage);
+  await pushModule.pushTag(info.newVersion, tagMessage);
   
   if (!options.quiet) {
-    console.log(`Tag ${info.nextVersion} created and pushed successfully.`);
+    console.log(`Tag ${info.newVersion} created and pushed successfully.`);
   }
 }
 
 async function main() {
   const [, , cmd, ...rest] = process.argv;
-  const options = parseArgs(cmd ? [cmd, ...rest] : rest);
+  
+  let options;
+  try {
+    options = parseArgs(cmd ? [cmd, ...rest] : rest);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error();
+    printHelp();
+    process.exit(1);
+    return;
+  }
 
   // Handle help
   if (cmd === '-h' || cmd === '--help' || cmd === 'help') {
@@ -129,13 +165,22 @@ async function main() {
   }
 
   // Unknown command (not an option)
-  if (cmd && !cmd.startsWith('--')) {
+  if (cmd && !cmd.startsWith('--') && !cmd.startsWith('-')) {
     console.error(`Error: Unknown command "${cmd}"`);
     console.error();
     printHelp();
     process.exit(1);
   }
 
+  // Invalid option (starts with -- but not valid)
+  if (cmd && cmd.startsWith('--') && !VALID_OPTIONS.includes(cmd)) {
+    console.error(`Error: Unknown option "${cmd}"`);
+    console.error();
+    printHelp();
+    process.exit(1);
+    return;
+  }
+
   // Default: show version info
   const info = await processVersionInfo();
   displayVersionInfo(info, options.quiet);

package/src/utils.js

@@ -67,6 +67,21 @@ const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'style', 'test', 'docs',
 const PATCH_TYPES = ['fix', 'perf', 'refactor', 'test', 'build', 'ci', 'revert'];
 const SEMVER_PATTERN = /^v(\d+)\.(\d+)\.(\d+)(-[a-zA-Z0-9.-]+)?$/;
 
+// Friendly header names for changelog
+const TYPE_HEADERS = {
+  feat: 'Features:',
+  fix: 'Fixes:',
+  perf: 'Performance:',
+  refactor: 'Refactors:',
+  style: 'Style:',
+  test: 'Tests:',
+  docs: 'Documentation:',
+  build: 'Build:',
+  ci: 'CI:',
+  chore: 'Chores:',
+  revert: 'Reverts:',
+};
+
 /**
  * Fetches tags from remote (non-destructive) if a remote is configured.
  * @returns {boolean} True if tags were fetched, false if using local tags only
@@ -155,13 +170,16 @@ function extractIssueReference(message) {
  * @param {string} subject - First line of commit message
  * @param {Object} parsed - Parsed conventional commit info
  * @param {string} fullMessage - Full commit message
+ * @param {boolean} isBreakingSection - Whether this is for the breaking changes section
  * @returns {string} Formatted description
  */
-function formatChangelogDescription(subject, parsed, fullMessage) {
+function formatChangelogDescription(subject, parsed, fullMessage, isBreakingSection = false) {
   if (!parsed) return subject;
   let description = parsed.description;
   const isBreaking = parsed.breaking || /BREAKING CHANGE:/i.test(fullMessage);
-  if (isBreaking) {
+  
+  // Only add BREAKING prefix if not in breaking changes section
+  if (isBreaking && !isBreakingSection) {
     description = `BREAKING: ${description}`;
   }
   return description;
@@ -214,13 +232,25 @@ function applyVersionBump(current, bump) {
   }
 }
 
+/**
+ * Checks if a commit is a breaking change.
+ * @param {Object} commit - Commit object
+ * @param {Object} parsed - Parsed conventional commit info
+ * @returns {boolean}
+ */
+function isBreakingChange(commit, parsed) {
+  if (!parsed) return false;
+  return parsed.breaking || /BREAKING CHANGE:/i.test(commit.message);
+}
+
 /**
  * Analyzes commits to determine version bump requirements.
  * @param {Array} commits - Array of commit objects
- * @returns {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean, commitsByType: Object}}
+ * @returns {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean, commitsByType: Object, breakingCommits: Array}}
  */
 function analyzeCommitsForVersioning(commits) {
   const commitsByType = Object.fromEntries(TYPE_ORDER.map(t => [t, []]));
+  const breakingCommits = [];
   let hasBreaking = false, hasFeat = false, hasPatchTypes = false;
   
   for (const commit of commits) {
@@ -228,26 +258,42 @@ function analyzeCommitsForVersioning(commits) {
     if (!parsed) continue;
     
     const { type, breaking } = parsed;
-    const isBreaking = breaking || /BREAKING CHANGE:/i.test(commit.message);
-    
-    if (isBreaking) hasBreaking = true;
-    if (type === 'feat') hasFeat = true;
-    else if (PATCH_TYPES.includes(type)) hasPatchTypes = true;
+    const isBreaking = isBreakingChange(commit, parsed);
     
-    if (commitsByType[type]) {
-      commitsByType[type].push(commit);
+    if (isBreaking) {
+      hasBreaking = true;
+      breakingCommits.push(commit);
+    } else {
+      // Only add to type sections if not breaking
+      if (type === 'feat') hasFeat = true;
+      else if (PATCH_TYPES.includes(type)) hasPatchTypes = true;
+      
+      if (commitsByType[type]) {
+        commitsByType[type].push(commit);
+      }
     }
   }
   
-  return { hasBreaking, hasFeat, hasPatchTypes, commitsByType };
+  return { hasBreaking, hasFeat, hasPatchTypes, commitsByType, breakingCommits };
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ * @param {string} str - The string to capitalize
+ * @returns {string} Capitalized string
+ */
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
 /**
  * Generates changelog entries for a commit type section.
  * @param {Array} commits - Commits of this type
+ * @param {boolean} isBreakingSection - Whether this is for the breaking changes section
  * @returns {Array<string>} Changelog lines
  */
-function generateTypeChangelog(commits) {
+function generateTypeChangelog(commits, isBreakingSection = false) {
   const byScope = {};
   const noScope = [];
   
@@ -258,7 +304,7 @@ function generateTypeChangelog(commits) {
     const subject = commit.message.split('\n')[0].trim();
     const entry = {
       scope: parsed.scope,
-      description: formatChangelogDescription(subject, parsed, commit.message),
+      description: formatChangelogDescription(subject, parsed, commit.message, isBreakingSection),
       issueRef: extractIssueReference(commit.message) || '',
     };
     
@@ -272,21 +318,21 @@ function generateTypeChangelog(commits) {
   const lines = [];
   for (const entry of noScope) {
     const ref = entry.issueRef ? ` ${entry.issueRef}` : '';
-    lines.push(`- ${entry.description}${ref}`);
+    lines.push(`- ${capitalize(entry.description)}${ref}`);
   }
   for (const scope of Object.keys(byScope).sort()) {
     for (const entry of byScope[scope]) {
       const ref = entry.issueRef ? ` ${entry.issueRef}` : '';
-      lines.push(`- **${scope}**: ${entry.description}${ref}`);
+      lines.push(`- ${scope}: ${capitalize(entry.description)}${ref}`);
     }
   }
   return lines;
 }
 
 /**
- * Calculates the next version and generates a changelog.
+ * Calculates the new version and generates a changelog.
  * @param {{latestVersion: string|null, commits: Array}} expandedInfo
- * @returns {{nextVersion: string|null, changelog: string}}
+ * @returns {{newVersion: string|null, changelog: string}}
  */
 function calculateNextVersionAndChangelog(expandedInfo) {
   const { latestVersion, commits } = expandedInfo;
@@ -294,15 +340,24 @@ function calculateNextVersionAndChangelog(expandedInfo) {
   const analysis = analyzeCommitsForVersioning(commits);
   
   const bump = determineVersionBumpType(analysis, current.major === 0);
-  const nextVersion = applyVersionBump(current, bump);
+  const newVersion = applyVersionBump(current, bump);
   
   // Generate changelog
   const changelogLines = [];
+  
+  // Add breaking changes section first if any
+  if (analysis.breakingCommits.length > 0) {
+    changelogLines.push('BREAKING CHANGES:');
+    changelogLines.push(...generateTypeChangelog(analysis.breakingCommits, true));
+    changelogLines.push('');
+  }
+  
+  // Add regular type sections
   for (const type of TYPE_ORDER) {
     const typeCommits = analysis.commitsByType[type];
     if (!typeCommits?.length) continue;
     
-    changelogLines.push(`### ${type}`);
+    changelogLines.push(TYPE_HEADERS[type] || `${capitalize(type)}:`);
     changelogLines.push(...generateTypeChangelog(typeCommits));
     changelogLines.push('');
   }
@@ -311,7 +366,7 @@ function calculateNextVersionAndChangelog(expandedInfo) {
     changelogLines.pop();
   }
   
-  return { nextVersion, changelog: changelogLines.join('\n') };
+  return { newVersion, changelog: changelogLines.join('\n') };
 }
 
 /**
@@ -357,7 +412,7 @@ function getAllBranchCommits(branch) {
 
 /**
  * Processes version information for the current branch.
- * @returns {Promise<{currentVersion: string|null, nextVersion: string|null, commits: Array, changelog: string}>}
+ * @returns {Promise<{currentVersion: string|null, newVersion: string|null, commits: Array, changelog: string}>}
  */
 async function processVersionInfo() {
   ensureGitRepo();
@@ -367,11 +422,11 @@ async function processVersionInfo() {
   const allCommits = getAllBranchCommits(branch);
   const expandedInfo = expandCommitInfo(allCommits);
   const { latestVersion, commits } = expandedInfo;
-  const { nextVersion, changelog } = calculateNextVersionAndChangelog(expandedInfo);
+  const { newVersion, changelog } = calculateNextVersionAndChangelog(expandedInfo);
   
   return {
     currentVersion: latestVersion,
-    nextVersion,
+    newVersion,
     commits,
     changelog,
   };