eslint-plugin-traceability 1.0.4 → 1.0.5

package/.github/workflows/ci-cd.yml

@@ -3,6 +3,8 @@ name: CI/CD Pipeline
 on:
   push:
     branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
   quality-checks:
@@ -14,6 +16,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -53,39 +57,43 @@ jobs:
         run: npm audit --audit-level=high
 
   deploy:
-    name: Deploy to NPM
+    if: ${{ github.event_name == 'push' }}
+    name: Release
     runs-on: ubuntu-latest
     needs: quality-checks
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    env:
+      HUSKY: 0
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20.x'
-          cache: npm
-          registry-url: 'https://registry.npmjs.org'
+          node-version: '22.x'
 
       - name: Install dependencies
         run: npm ci
 
-      - name: Build project
-        run: npm run build
-
-      - name: Publish to npm
+      - name: Release with semantic-release
+        run: npx semantic-release
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --access public
-
-      - name: Pack plugin
-        run: npm pack
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      - name: Smoke Test Plugin Tarball
+      - name: Smoke test published package
         run: |
-          mkdir temp
-          cd temp
-          npm init -y
-          npm install ../eslint-plugin-traceability-*.tgz --no-save
+          echo "Smoke testing eslint-plugin-traceability"
+          workdir=$(mktemp -d)
+          cd "$workdir"
+          npm init -y > /dev/null
+          npm install eslint-plugin-traceability > /dev/null
           echo '{"plugins":["traceability"],"rules":{}}' > .eslintrc.json
           npx eslint --print-config .

package/.husky/pre-commit

@@ -1 +1 @@
-npm run format && npm run lint -- --max-warnings=0 && npm run type-check
+npm run format && npm run lint -- --max-warnings=0 && npm run type-check && node node_modules/actionlint/actionlint.cjs .github/workflows/*.yml

package/.releaserc.json

@@ -0,0 +1,15 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.0.5](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.0.4...v1.0.5) (2025-11-17)
+
+
+### Bug Fixes
+
+* remove @semantic-release/git plugin to prevent version commits ([277a0cc](https://github.com/voder-ai/eslint-plugin-traceability/commit/277a0cc5389ea43d41c1a277ec6929cac3104633))
+
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -47,4 +54,4 @@ All notable changes to this project will be documented in this file.
 - Comprehensive tests covering core validation rules.
 
 ### Fixed
-- N/A
+- N/A

package/CONTRIBUTING.md

@@ -27,26 +27,28 @@ When submitting a pull request (PR):
 
 ## Commit Message Conventions
 
-We follow [Conventional Commits](https://www.conventionalcommits.org/) format. Commit messages should be structured as:
+We follow [Conventional Commits](https://www.conventionalcommits.org/) format to enable automated semantic versioning and changelog generation.
+
+For detailed guidelines and examples, see [docs/conventional-commits-guide.md](docs/conventional-commits-guide.md).
+
+Commit messages should be structured as:
 
 ```
-tag: short description
+type[optional scope]: description
 
-optional body explaining why the change was made
+[optional body]
 
-optional footer (e.g., BREAKING CHANGE: ...)
+[optional footer(s)]
 ```
 
-Common commit types:
+Examples:
+
+- `feat: add new validation rule` → minor version increment
+- `fix: resolve parsing issue` → patch version increment
+- `feat!: change API interface` → major version increment
+- `docs: update README` → no version change
 
-- `feat:` A new feature
-- `fix:` A bug fix
-- `docs:` Documentation only changes
-- `style:` Code style changes (formatting, linting)
-- `refactor:` Code changes that neither fix a bug nor add a feature
-- `perf:` Performance improvements
-- `test:` Adding or updating tests
-- `chore:` Other changes that do not modify src or test files
+Common types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
 
 ## Coding Style and Quality Checks
 

package/docs/conventional-commits-guide.md

@@ -0,0 +1,185 @@
+# Conventional Commits Guide
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) to enable automated semantic versioning and changelog generation through semantic-release.
+
+## Commit Message Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types and Version Impact
+
+### `feat`: New Features (Minor Version)
+
+- Adds new functionality
+- Results in a **minor** version increment (e.g., 1.0.0 → 1.1.0)
+
+Examples:
+
+```bash
+feat: add new validation rule for story references
+feat(rules): implement require-branch-annotation rule
+feat: add CLI integration for batch processing
+```
+
+### `fix`: Bug Fixes (Patch Version)
+
+- Fixes existing functionality
+- Results in a **patch** version increment (e.g., 1.0.0 → 1.0.1)
+
+Examples:
+
+```bash
+fix: resolve annotation parsing for multiline comments
+fix(validation): handle edge case in reference checking
+fix: prevent false positives in story reference detection
+```
+
+### Breaking Changes (Major Version)
+
+- Any commit with `!` after the type or `BREAKING CHANGE:` in footer
+- Results in a **major** version increment (e.g., 1.0.0 → 2.0.0)
+
+Examples:
+
+```bash
+feat!: change API interface for rule configuration
+fix!: remove deprecated annotation format support
+
+feat: add new validation options
+
+BREAKING CHANGE: The `allowUnresolved` option has been removed.
+Use `strict: false` instead.
+```
+
+### Other Types (No Version Change)
+
+These don't trigger releases but appear in changelog:
+
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring without functional changes
+- `test`: Adding or updating tests
+- `chore`: Build process, auxiliary tools, or maintenance
+- `perf`: Performance improvements
+- `ci`: CI/CD configuration changes
+
+Examples:
+
+```bash
+docs: update README with installation instructions
+test: add unit tests for validation rules
+chore: update dependencies to latest versions
+ci: configure semantic-release for automated publishing
+```
+
+## Scopes (Optional)
+
+Use scopes to specify what part of the codebase is affected:
+
+- `rules`: ESLint rule implementations
+- `maintenance`: Maintenance scripts and utilities
+- `cli`: Command-line integration tools
+- `config`: Configuration and setup files
+- `deps`: Dependency updates
+
+Examples:
+
+```bash
+feat(rules): add valid-annotation-format rule
+fix(maintenance): resolve batch processing memory leak
+docs(config): add ESLint 9 setup guide
+```
+
+## Best Practices
+
+### Commit Message Guidelines
+
+1. **Use imperative mood**: "add feature" not "added feature"
+2. **Keep subject under 50 characters**: For better git log readability
+3. **Capitalize the subject line**: Start with capital letter
+4. **No period at the end**: Of the subject line
+5. **Explain what and why**: In the body, not how
+
+### When to Use Each Type
+
+**Use `feat` when:**
+
+- Adding new ESLint rules
+- Adding new maintenance utilities
+- Adding new configuration options
+- Adding new CLI commands or features
+
+**Use `fix` when:**
+
+- Fixing rule logic or false positives/negatives
+- Fixing crashes or runtime errors
+- Fixing configuration issues
+- Fixing documentation errors
+
+**Use `refactor` when:**
+
+- Improving code structure without changing behavior
+- Renaming variables or functions
+- Extracting common functionality
+- Simplifying complex logic
+
+**Use `docs` when:**
+
+- Updating README, guides, or API documentation
+- Adding code comments or JSDoc
+- Updating examples or migration guides
+
+### Example Workflow
+
+```bash
+# New feature
+git commit -m "feat(rules): add require-story-annotation rule
+
+Implements validation to ensure all functions have @story annotations
+linking them to user stories for traceability.
+
+Resolves: #123"
+
+# Bug fix
+git commit -m "fix: resolve false positive in annotation parsing
+
+The regex pattern was incorrectly matching inline comments.
+Updated to only match block comments that start at beginning of line."
+
+# Breaking change
+git commit -m "feat!: change rule configuration schema
+
+BREAKING CHANGE: Rule options now use 'patterns' instead of 'pattern'.
+Update your ESLint config:
+- Before: { "pattern": "REQ-*" }
++ After: { "patterns": ["REQ-*"] }"
+```
+
+## Integration with semantic-release
+
+semantic-release analyzes commit messages to:
+
+1. **Determine version bump**: Based on feat/fix/breaking change types
+2. **Generate changelog**: From commit messages and pull request information
+3. **Create git tags**: For each release
+4. **Publish to npm**: Only when changes warrant a release
+
+## Validation
+
+Pre-commit hooks will validate your commit messages follow the conventional format. If you need to bypass validation temporarily (not recommended), use:
+
+```bash
+git commit --no-verify -m "your message"
+```
+
+## Resources
+
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [semantic-release Documentation](https://semantic-release.gitbook.io/)
+- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format)

package/docs/decisions/004-automated-version-bumping-for-ci-cd.md

@@ -1,5 +1,5 @@
 ---
-status: "proposed"
+status: "superseded"
 date: 2025-11-17
 decision-makers: [Development Team]
 consulted:
@@ -9,6 +9,8 @@ consulted:
     Semantic Versioning Specification,
   ]
 informed: [Project Stakeholders, CI/CD Pipeline Maintainers]
+superseded-by: "006-semantic-release-for-automated-publishing"
+superseded-date: "2025-11-17"
 ---
 
 # Automated Version Bumping for CI/CD Publishing

package/docs/decisions/006-semantic-release-for-automated-publishing.accepted.md

@@ -0,0 +1,227 @@
+---
+status: "accepted"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    semantic-release Documentation,
+    Conventional Commits Specification,
+    GitHub Actions Best Practices,
+    npm Publishing Guidelines,
+  ]
+informed: [Project Stakeholders, CI/CD Pipeline Maintainers]
+---
+
+# Semantic Release for Automated Publishing
+
+## Context and Problem Statement
+
+The current automated version bumping strategy (ADR 004) has several limitations that impact maintainability and developer experience:
+
+1. **Single Increment Logic**: The CI/CD pipeline only increments the version once, requiring complex loop logic to handle cases where multiple increments are needed (e.g., when both 1.0.3 and 1.0.4 already exist on npm)
+
+2. **No Semantic Version Determination**: The system only performs patch increments and cannot automatically determine when minor or major version bumps are appropriate based on the nature of changes
+
+3. **Missing Release Management**: No automatic git tagging, release notes, or CHANGELOG.md generation, reducing traceability and release visibility
+
+4. **Workflow Complexity**: The custom version increment logic in GitHub Actions is becoming complex and error-prone, potentially violating workflow validation best practices established in ADR 005
+
+5. **Package.json/npm Version Drift**: The package.json version in the repository can lag behind the published npm version, creating confusion about the actual release state
+
+The current approach was designed as a temporary solution to prevent npm publish failures, but its limitations suggest that a more comprehensive release automation strategy is needed.
+
+## Decision Drivers
+
+- Need for proper semantic version determination based on change significance
+- Automatic generation of release notes and changelog maintenance
+- Git tag creation for release tracking and traceability
+- Elimination of complex custom version increment logic in CI/CD workflows
+- Integration with conventional commit standards for automated version type detection
+- Prevention of unnecessary publishing when no changes warrant a release
+- Alignment with npm ecosystem best practices for release management
+- Simplification of GitHub Actions workflow to improve maintainability and validation compliance
+
+## Considered Options
+
+- Enhance current in-memory version increment approach with loop logic
+- Implement semantic-release with conventional commits
+- Switch to git write-back approach with automated tagging
+- Implement manual release workflow with GitHub releases
+
+## Decision Outcome
+
+Chosen option: "semantic-release with conventional commits", because it provides comprehensive release automation, proper semantic versioning, automated changelog generation, and eliminates the need for complex custom version logic while following industry standards.
+
+### Implementation Strategy
+
+1. **Install and Configure semantic-release**:
+   - Add `semantic-release` and related plugins as development dependencies
+   - Configure semantic-release with conventional commits preset
+   - Set up plugins for npm publishing, git tagging, and changelog generation
+
+2. **Establish Conventional Commit Standards**:
+   - Adopt conventional commit message format for semantic version determination
+   - Configure semantic-release to analyze commit messages for version impact
+   - Document commit message guidelines for contributors
+
+3. **Update CI/CD Pipeline**:
+   - Replace custom version increment logic with semantic-release execution
+   - Configure semantic-release to run on main branch pushes
+   - Set up proper npm registry authentication and git permissions
+
+4. **Configure Release Automation**:
+   - Automatic CHANGELOG.md generation and maintenance
+   - Git tag creation for each release
+   - GitHub release creation with release notes
+   - Conditional publishing (only when changes warrant a release)
+
+### Consequences
+
+- Good, because eliminates complex custom version increment logic from CI/CD workflows
+- Good, because provides proper semantic version determination based on commit analysis
+- Good, because automatically generates and maintains CHANGELOG.md with release notes
+- Good, because creates proper git tags and GitHub releases for traceability
+- Good, because follows conventional commits standard adopted widely in open source
+- Good, because only publishes when changes actually warrant a new release
+- Good, because avoids package.json version drift by using git tags as source of truth
+- Good, because simplifies GitHub Actions workflow, improving validation compliance
+- Good, because provides comprehensive release management with minimal configuration
+- Good, because prevents infinite CI loops from version commits
+- Neutral, because requires team adoption of conventional commit message format
+- Neutral, because package.json version in repository may lag behind published version (git tags are source of truth)
+- Bad, because introduces dependency on semantic-release tool and its ecosystem
+- Bad, because may require learning curve for conventional commit message format
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- semantic-release successfully analyzes commits and determines appropriate version increments
+- Automatic CHANGELOG.md generation and git tag creation on releases
+- CI/CD pipeline publishes to npm only when semantic-release determines a release is warranted
+- No npm publish failures due to version conflicts or unnecessary publishing attempts
+- Package.json version remains synchronized with published npm version
+- GitHub Actions workflow simplified and validates successfully with actionlint (ADR 005)
+- Conventional commit message format adopted and documented for contributors
+
+## Pros and Cons of the Options
+
+### semantic-release with conventional commits
+
+Comprehensive automated release management based on commit message analysis.
+
+- Good, because industry standard tool with extensive ecosystem
+- Good, because proper semantic version determination based on commit analysis
+- Good, because automatic CHANGELOG.md and release notes generation
+- Good, because creates git tags and GitHub releases automatically
+- Good, because only publishes when changes warrant a release
+- Good, because eliminates custom version increment logic complexity
+- Good, because maintains git history and package.json synchronization
+- Good, because follows conventional commits standard
+- Good, because comprehensive documentation and community support
+- Neutral, because requires conventional commit message discipline
+- Neutral, because adds dependency on semantic-release ecosystem
+- Bad, because requires git write permissions in CI/CD
+- Bad, because learning curve for commit message conventions
+
+### Enhanced in-memory version increment with loop logic
+
+Improve the current approach with better version conflict resolution.
+
+- Good, because builds on existing working foundation
+- Good, because no external dependencies or new tooling
+- Good, because maintains current simplicity of git read-only CI/CD
+- Neutral, because addresses immediate technical limitation
+- Bad, because still provides only patch-level version increments
+- Bad, because no semantic version determination capability
+- Bad, because no automatic changelog or git tag generation
+- Bad, because increases complexity of custom GitHub Actions logic
+- Bad, because doesn't address package.json/npm version synchronization
+- Bad, because potential for workflow validation issues with complex logic
+
+### Git write-back approach with automated tagging
+
+Custom solution with git operations for version commits and tagging.
+
+- Good, because provides git tag creation and version history
+- Good, because maintains package.json synchronization
+- Good, because can be customized for specific project needs
+- Neutral, because requires git write permissions
+- Bad, because requires complex infinite loop prevention logic
+- Bad, because no semantic version determination
+- Bad, because no automated changelog generation
+- Bad, because potential race conditions in CI/CD
+- Bad, because increased failure modes with git operations
+- Bad, because custom implementation maintenance burden
+
+### Manual release workflow with GitHub releases
+
+Manual release creation through GitHub interface with automated publishing.
+
+- Good, because provides full control over release timing and messaging
+- Good, because natural integration with GitHub releases interface
+- Good, because allows for manual changelog and release notes
+- Good, because no automated commit message requirements
+- Neutral, because requires manual intervention for releases
+- Bad, because breaks continuous delivery principle
+- Bad, because prone to human error and forgotten releases
+- Bad, because no automation of version determination
+- Bad, because workflow friction for regular development
+- Bad, because doesn't solve original npm publish failure problem
+
+## More Information
+
+This decision supersedes ADR 004 "Automated Version Bumping for CI/CD Publishing", which served as a temporary solution to prevent npm publish failures but has reached its limitations in terms of semantic versioning and release management.
+
+semantic-release configuration will include:
+
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}
+```
+
+**Note**: The `@semantic-release/git` plugin is intentionally excluded. semantic-release will manage versions through git tags only, without committing version changes back to package.json. This approach:
+
+- Prevents infinite CI loops from version commits
+- Follows npm ecosystem best practices where tags are the source of truth
+- Keeps the repository history clean of automated version bump commits
+- Aligns with how other projects in the ecosystem use semantic-release
+
+The published npm package will have the correct version, but package.json in the repository may not reflect the latest published version. Git tags serve as the authoritative version record.
+
+Conventional commit format examples:
+
+- `feat: add new validation rule` → minor version increment
+- `fix: resolve annotation parsing issue` → patch version increment
+- `feat!: change API interface` → major version increment
+- `docs: update README` → no version increment
+
+GitHub Actions workflow simplification:
+
+- Remove custom version increment logic
+- Replace with single `npx semantic-release` command
+- Configure necessary permissions (contents:write, issues:write, pull-requests:write, id-token:write)
+- Set HUSKY=0 environment variable to disable git hooks during release
+- Maintain existing quality checks and security audits
+- Add smoke test for published package verification
+
+This decision should be re-evaluated if:
+
+- Conventional commit discipline becomes difficult to maintain
+- semantic-release ecosystem introduces breaking changes or maintenance issues
+- Project requirements change to need custom release logic not supported by semantic-release
+- Team prefers different commit message standards incompatible with conventional commits
+
+Related resources:
+
+- [semantic-release Documentation](https://semantic-release.gitbook.io/)
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [GitHub Actions with semantic-release](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/github-actions.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -41,17 +41,22 @@
   "homepage": "https://github.com/voder-ai/eslint-plugin-traceability#readme",
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
     "@types/eslint": "^9.6.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
     "@typescript-eslint/parser": "^8.46.4",
     "@typescript-eslint/utils": "^8.46.4",
+    "actionlint": "^2.0.6",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.6",
     "prettier": "^3.6.2",
+    "semantic-release": "^25.0.2",
     "ts-jest": "^29.4.5",
     "typescript": "^5.9.3"
   },
@@ -64,4 +69,4 @@
   "overrides": {
     "js-yaml": ">=4.1.1"
   }
-}
+}