build(cli): introducing Semantic-Version to control the CLI version

.github/workflows/publish-cli-to-npm.yml → .github/workflows/release-cli.yml

@@ -1,37 +1,41 @@
-name: Publish CLI to NPM
-
-permissions:
-    contents: read
-
-on:
-    release:
-        types: [published]
-
-jobs:
-    publish-cli:
-        runs-on: ubuntu-latest
-        steps:
-            # Checkout the code
-            - name: Checkout code
-              uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-
-            # Set up Node.js
-            - name: Setup Node.js
-              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-              with:
-                  node-version: v22
-                  registry-url: 'https://registry.npmjs.org'
-
-            # Install the workspace
-            - name: Install workspace
-              run: npm ci
-
-            # Build the entire workspace
-            - name: Build workspace
-              run: npm run build
-
-            # Publish the CLI module
-            - name: Publish CLI module
-              run: npm publish --workspace cli
-              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+name: Release and Publish CLI
+
+permissions:
+    contents: write
+    issues: write
+    pull-requests: write
+
+on:
+    workflow_dispatch:
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+        steps:
+            # Checkout the code with full history for semantic-release
+            - name: Checkout code
+              uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+              with:
+                  fetch-depth: 0
+
+            # Set up Node.js
+            - name: Setup Node.js
+              uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+              with:
+                  node-version: v22
+                  registry-url: 'https://registry.npmjs.org'
+
+            # Install the workspace
+            - name: Install workspace
+              run: npm ci
+
+            # Build the entire workspace
+            - name: Build workspace
+              run: npm run build
+
+            # Run semantic-release for CLI
+            - name: Release CLI
+              run: npm run semantic-release --workspace cli
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/validate-pr-commits.yml

@@ -0,0 +1,134 @@
+name: Validate PR Commit Messages
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  validate-commits:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: v22
+
+      - name: Install commitlint dependencies
+        run: |
+          npm install @commitlint/cli@^19.5.0 @commitlint/config-conventional@^19.5.0
+
+      - name: Validate commit messages
+        run: |
+          # Get the base branch (usually main)
+          BASE_SHA=$(git merge-base origin/${{ github.base_ref }} HEAD)
+
+          # Validate all commits in the PR
+          npx commitlint --from $BASE_SHA --to HEAD --verbose
+
+      - name: Comment on PR if validation fails
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const message = `## ❌ Commit Message Validation Failed
+
+            Some commit messages in this PR don't follow the [Conventional Commits](https://conventionalcommits.org/) specification.
+
+            ### Required Format:
+            \`\`\`
+            <type>[optional scope]: <description>
+
+            [optional body]
+
+            [optional footer(s)]
+            \`\`\`
+
+            ### Valid Types:
+            - **feat**: A new feature (triggers a minor release)
+            - **fix**: A bug fix (triggers a patch release) 
+            - **docs**: Documentation only changes
+            - **style**: Changes that do not affect the meaning of the code
+            - **refactor**: A code change that neither fixes a bug nor adds a feature
+            - **perf**: A code change that improves performance
+            - **test**: Adding missing tests or correcting existing tests
+            - **build**: Changes that affect the build system or external dependencies
+            - **ci**: Changes to our CI configuration files and scripts
+            - **chore**: Other changes that don't modify src or test files
+
+            ### Valid Scopes:
+            - \`cli\`: Changes specific to the CLI package
+            - \`shared\`: Changes to shared utilities
+            - \`calm\`: Changes to the CALM spec
+            - \`calm-widgets\`: Changes to the widgets package
+            - \`calm-hub\`: Changes to the hub backend
+            - \`calm-hub-ui\`: Changes to the hub frontend
+            - \`docs\`: Changes to documentation
+            - \`workspace\`: Changes affecting the entire workspace
+
+            ### Examples:
+            - \`feat(cli): add new validation command\`
+            - \`fix(shared): resolve parsing issue with YAML files\`
+            - \`docs: update README with installation instructions\`
+            - \`feat!: remove deprecated API endpoints\` (breaking change)
+
+            ### For Breaking Changes:
+            Add \`!\` after the type or include \`BREAKING CHANGE:\` in the commit footer.
+
+            Please update your commit messages to follow this format. You can use \`git rebase -i\` to edit commit messages, or squash commits and create new ones with proper formatting.
+
+            You can also use \`npm run commit\` in the repository to get guided commit message creation.`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: message
+            });
+
+      - name: Comment on PR if validation succeeds
+        if: success()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const message = `## ✅ Commit Message Validation Passed
+
+            All commit messages in this PR follow the [Conventional Commits](https://conventionalcommits.org/) specification. Great job! 🎉
+
+            This means semantic-release will be able to properly analyze the changes and determine the appropriate version bump when this PR is merged.`;
+
+            // Check if we already commented on this PR
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            });
+
+            const existingComment = comments.data.find(comment => 
+              comment.body.includes('Commit Message Validation') && 
+              comment.user.type === 'Bot'
+            );
+
+            if (existingComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                comment_id: existingComment.id,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: message
+              });
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: message
+              });
+            }

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

SEMANTIC_RELEASE.md

@@ -0,0 +1,105 @@
+# Semantic Release Setup for CLI
+
+This project uses semantic-release to automatically manage versioning and publishing of the `@finos/calm-cli` package.
+
+## How it works
+
+- **Automated Versioning**: Version numbers are automatically determined based on the semantic meaning of commits
+- **Manual Release Control**: Releases are triggered manually when you're ready to publish
+- **Changelog Generation**: A changelog is automatically generated and maintained
+- **GitHub Releases**: GitHub releases are automatically created with release notes
+
+## Commit Message Format
+
+This project follows the [Conventional Commits](https://conventionalcommits.org/) specification. All commit messages should be structured as follows:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- **feat**: A new feature (triggers a minor release)
+- **fix**: A bug fix (triggers a patch release)
+- **docs**: Documentation only changes (triggers a patch release)
+- **style**: Changes that do not affect the meaning of the code (triggers a patch release)
+- **refactor**: A code change that neither fixes a bug nor adds a feature (triggers a patch release)
+- **perf**: A code change that improves performance (triggers a patch release)
+- **test**: Adding missing tests or correcting existing tests
+- **build**: Changes that affect the build system or external dependencies
+- **ci**: Changes to our CI configuration files and scripts
+- **chore**: Other changes that don't modify src or test files
+
+### Breaking Changes
+
+To trigger a major release, include `BREAKING CHANGE:` in the commit footer or add a `!` after the type:
+
+```
+feat!: remove deprecated API endpoints
+
+BREAKING CHANGE: The old v1 API endpoints have been removed
+```
+
+### Scopes
+
+Available scopes include:
+- `cli`: Changes specific to the CLI package
+- `shared`: Changes to shared utilities
+- `calm`: Changes to the CALM spec
+- `calm-widgets`: Changes to the widgets package
+- `calm-hub`: Changes to the hub backend
+- `calm-hub-ui`: Changes to the hub frontend
+- `docs`: Changes to documentation
+- `workspace`: Changes affecting the entire workspace
+
+## Using Commitizen
+
+To help create properly formatted commits, you can use commitizen:
+
+```bash
+npm run commit
+```
+
+This will prompt you through creating a conventional commit message.
+
+## PR Validation
+
+Every pull request automatically validates that all commit messages follow the conventional commit format:
+
+- **Automatic Checks**: When you open or update a PR, all commit messages are validated
+- **Status Checks**: PRs with invalid commit messages will fail the validation check
+- **Helpful Feedback**: The bot will comment on your PR with specific guidance if commits need fixing
+- **Examples Provided**: Get clear examples of proper commit message format
+- **Scope Validation**: Ensures you're using valid scopes for this project
+
+### If Validation Fails
+
+If your commit messages don't follow the conventional format:
+1. The PR check will fail
+2. A bot will comment with detailed guidance
+3. You can fix commits using `git rebase -i` to edit messages
+4. Or squash and create new commits with proper formatting
+5. Use `npm run commit` for guided commit creation
+
+## Workflow
+
+1. Make your changes
+2. Use `npm run commit` or write a conventional commit message manually
+3. Push to a feature branch and create a PR
+   - **Automatic Validation**: The PR will automatically validate all commit messages
+   - **Status Checks**: The PR validation must pass before merging
+   - **Helpful Comments**: Get feedback if commit messages need fixing
+4. When you're ready to release:
+   - Go to the GitHub Actions tab in the repository
+   - Run the "Release and Publish CLI" workflow manually
+5. The workflow will:
+   - Analyze the commits since the last release to determine the version bump
+   - Update the version in `cli/package.json`
+   - Generate/update the `cli/CHANGELOG.md`
+   - Create a Git tag
+   - Publish to NPM
+   - Create a GitHub release

cli/.releaserc.json

@@ -0,0 +1,64 @@
+{
+  "repositoryUrl": "https://github.com/finos/architecture-as-code.git",
+  "branches": [
+    "main",
+    {
+      "name": "beta",
+      "prerelease": true
+    }
+  ],
+  "tagFormat": "cli-v${version}",
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "angular",
+        "releaseRules": [
+          { "type": "docs", "scope": "README", "release": "patch" },
+          { "type": "refactor", "release": "patch" },
+          { "type": "style", "release": "patch" }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "angular"
+      }
+    ],
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": true,
+        "tarballDir": "dist"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "CHANGELOG.md"
+        ],
+        "message": "chore(cli): release ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "assets": [
+          {
+            "path": "dist/*.tgz",
+            "label": "CLI Package"
+          }
+        ]
+      }
+    ]
+  ]
+}

cli/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.8.0] - 2025-08-08
+
+### Added
+- Initial version with semantic-release configuration
+- Automated version management using conventional commits