eslint-plugin-traceability 1.1.1 → 1.1.3

package/docs/decisions/005-github-actions-validation-tooling.accepted.md

@@ -1,144 +0,0 @@
----
-status: "accepted"
-date: 2025-11-17
-decision-makers: [Development Team]
-consulted:
-  [
-    GitHub Actions Documentation,
-    Super-Linter Community,
-    actionlint Documentation,
-  ]
-informed: [Project Contributors, CI/CD Pipeline Maintainers]
----
-
-# GitHub Actions Validation Tooling Selection
-
-## Context and Problem Statement
-
-The project uses GitHub Actions for CI/CD workflows defined in `.github/workflows/`. To prevent broken GitHub Actions files from being pushed to the repository, we need to implement pre-commit validation for GitHub Actions YAML files. This validation should catch syntax errors, invalid action references, and misconfigured job dependencies before they are committed, as broken workflow files could prevent CI/CD from running at all.
-
-## Decision Drivers
-
-- Need for pre-commit validation to prevent broken GitHub Actions files from being pushed
-- Performance requirements for fast local development workflows
-- Prevention of workflow files that would break CI/CD execution
-- Integration with existing development tools and pre-commit hooks
-- Maintainability and configuration simplicity
-- Resource efficiency for local development environments
-
-## Considered Options
-
-- actionlint for pre-commit hooks only
-- actionlint for both pre-commit and CI/CD
-- Super-Linter for pre-commit hooks
-- GitHub's built-in validation only
-
-## Decision Outcome
-
-Chosen option: "actionlint for pre-commit hooks only", because it prevents broken GitHub Actions files from being pushed while maintaining fast local development workflow. Once files reach CI/CD, if the workflow runs successfully, the files are valid by definition.
-
-### Consequences
-
-- Good, because actionlint provides fast pre-commit validation without container overhead
-- Good, because prevents broken GitHub Actions files from being pushed
-- Good, because specifically designed for GitHub Actions validation
-- Good, because simple configuration and maintenance
-- Good, because no Docker dependencies for local development
-- Good, because excellent performance for pre-commit hooks
-- Good, because integrates seamlessly with existing Husky-based pre-commit hooks
-- Neutral, because CI/CD validation is unnecessary if workflows execute successfully
-- Bad, because limited to GitHub Actions validation only
-- Bad, because no security vulnerability detection in pre-commit phase
-
-### Confirmation
-
-Implementation compliance will be confirmed through:
-
-- actionlint added to Husky pre-commit hook in `.husky/pre-commit`
-- Pre-commit hook blocks commits with GitHub Actions validation errors
-- actionlint configured to validate files in `.github/workflows/`
-- Documentation updated to explain Husky-based pre-commit validation approach
-
-### Implementation Approach
-
-actionlint will be integrated into existing Husky-based pre-commit hooks by:
-
-- Installing actionlint as a development dependency
-- Adding actionlint validation to `.husky/pre-commit` hook
-- Configuring actionlint to check `.github/workflows/*.yml` files
-- Documenting the validation process for contributors
-
-## Pros and Cons of the Options
-
-### actionlint for pre-commit hooks only
-
-Lightweight, focused pre-commit validation to prevent broken GitHub Actions files.
-
-- Good, because fast execution without container overhead
-- Good, because specifically designed for GitHub Actions validation
-- Good, because no Docker dependencies for local development
-- Good, because simple configuration and maintenance
-- Good, because excellent performance for pre-commit hooks
-- Good, because prevents broken workflow files from being pushed
-- Good, because minimal tooling - only runs where validation is needed
-- Neutral, because focused scope reduces complexity
-- Neutral, because CI/CD validation unnecessary if workflows execute successfully
-- Bad, because limited to GitHub Actions validation only
-- Bad, because no security vulnerability detection in pre-commit phase
-
-### actionlint for both pre-commit and CI/CD
-
-Validation in both development and CI/CD environments.
-
-- Good, because fast execution in all environments
-- Good, because specifically designed for GitHub Actions
-- Good, because consistent validation across environments
-- Neutral, because focused scope reduces complexity
-- Bad, because unnecessary duplication - CI/CD execution validates workflow correctness
-- Bad, because adds CI/CD overhead for validation that's already proven by execution
-- Bad, because limited to GitHub Actions validation only
-
-### Super-Linter for pre-commit hooks
-
-Comprehensive linting solution for pre-commit validation.
-
-- Good, because comprehensive validation including security checks
-- Good, because validates multiple file types beyond GitHub Actions
-- Neutral, because well-maintained and widely adopted
-- Bad, because container overhead makes pre-commit hooks slow
-- Bad, because heavy resource usage for simple syntax checking
-- Bad, because Docker dependency required for local development
-- Bad, because not optimized for frequent pre-commit execution
-- Bad, because overkill for the specific problem of preventing broken workflow files
-
-### GitHub's built-in validation only
-
-Rely solely on GitHub's native workflow validation.
-
-- Good, because no additional tooling or configuration required
-- Good, because automatically available in GitHub interface
-- Good, because validated by the same system that executes workflows
-- Neutral, because basic validation is always performed
-- Bad, because no pre-commit validation for early error detection
-- Bad, because broken files can be pushed, preventing CI/CD execution
-- Bad, because errors only discovered after push to repository
-- Bad, because no local development feedback
-
-## More Information
-
-This decision focuses on solving the specific problem of preventing broken GitHub Actions files from being pushed to the repository. If CI/CD workflows execute successfully, the files are validated by definition - there's no need for redundant validation in the CI/CD pipeline itself.
-
-actionlint configuration should be added to the existing Husky pre-commit hook in `.husky/pre-commit`, targeting `.github/workflows/*.yml` files to catch syntax and configuration errors before commit.
-
-The decision should be re-evaluated if:
-
-- Security vulnerability detection becomes a requirement for pre-commit validation
-- Comprehensive multi-language linting becomes necessary for pre-commit
-- Alternative tools with better GitHub Actions-specific features emerge
-- The problem scope expands beyond preventing broken workflow files
-
-Related resources:
-
-- [actionlint Documentation](https://github.com/rhymond/actionlint)
-- [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
-- [Husky Documentation](https://typicode.github.io/husky/)

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

@@ -1,227 +0,0 @@
----
-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)