eslint-plugin-traceability 1.7.0 → 1.8.0

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/docs/decisions/007-github-releases-over-changelog.accepted.md

@@ -0,0 +1,216 @@
+---
+status: "accepted"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    semantic-release Documentation,
+    GitHub Releases Best Practices,
+    Open Source Project Standards,
+  ]
+informed: [Project Contributors, Package Users]
+---
+
+# GitHub Releases Over Manual CHANGELOG.md Maintenance
+
+## Context and Problem Statement
+
+With the adoption of semantic-release (ADR 006), the project now has automated changelog generation and GitHub release creation capabilities. However, we currently maintain a manual CHANGELOG.md file that duplicates this information and creates several issues:
+
+1. **Duplicate Effort**: semantic-release automatically generates release notes and CHANGELOG.md content, making manual maintenance redundant
+
+2. **Synchronization Risk**: Manual CHANGELOG.md updates can become out of sync with actual releases, creating confusion about what changes were included in which version
+
+3. **Source of Truth Ambiguity**: Having both a manual CHANGELOG.md and automated GitHub Releases creates uncertainty about which source is authoritative for release information
+
+4. **Maintenance Burden**: Developers must remember to update CHANGELOG.md manually in addition to following conventional commit standards, increasing cognitive load
+
+5. **Incomplete Historical Record**: Manual changelogs are prone to omissions, while automated generation from commits provides complete traceability
+
+The current CHANGELOG.md was valuable during manual release management, but semantic-release provides a superior automated alternative that eliminates these problems.
+
+## Decision Drivers
+
+- Elimination of duplicate changelog maintenance effort
+- Single source of truth for release information
+- Consistency between commits, releases, and changelog
+- Leveraging semantic-release capabilities fully
+- Reducing manual maintenance burden on developers
+- Following modern open source project practices
+- Improving traceability from commits to releases
+- Preventing changelog/release synchronization issues
+
+## Considered Options
+
+- Continue maintaining both manual CHANGELOG.md and GitHub Releases
+- Use CHANGELOG.md as redirect to GitHub Releases page
+- Completely remove CHANGELOG.md file
+- Keep manual CHANGELOG.md and disable semantic-release changelog generation
+
+## Decision Outcome
+
+Chosen option: "Use CHANGELOG.md as redirect to GitHub Releases page", because it maintains backward compatibility for users who expect a CHANGELOG.md file while directing them to the authoritative and automatically maintained release information on GitHub.
+
+### Implementation Strategy
+
+1. **Replace CHANGELOG.md Content**:
+   - Replace current content with a simple redirect message
+   - Include link to GitHub Releases page
+   - Provide brief explanation of why releases are maintained on GitHub
+   - Keep file in repository to avoid breaking tooling that expects it
+
+2. **Configure semantic-release**:
+   - Ensure semantic-release is configured to create GitHub Releases with complete release notes
+   - Verify automated release notes include all commit types appropriately
+   - Maintain git tags as authoritative version markers
+
+3. **Update Documentation**:
+   - Update contributing guidelines to reference GitHub Releases
+   - Document that changelog is maintained automatically via semantic-release
+   - Remove any references to manual CHANGELOG.md maintenance
+
+4. **Archive Historical Content**:
+   - Historical CHANGELOG.md content remains in git history
+   - Previous releases maintain their existing changelog entries
+   - New releases will be documented exclusively on GitHub
+
+### Consequences
+
+- Good, because eliminates duplicate changelog maintenance effort
+- Good, because provides single source of truth (GitHub Releases)
+- Good, because leverages semantic-release automation fully
+- Good, because ensures changelog is always synchronized with releases
+- Good, because provides richer release information (links, commits, contributors)
+- Good, because maintains backward compatibility with CHANGELOG.md file presence
+- Good, because follows modern open source project conventions
+- Good, because reduces manual maintenance burden on developers
+- Good, because improves traceability from commits through releases
+- Neutral, because requires users to access GitHub for detailed release information
+- Neutral, because CHANGELOG.md becomes a pointer rather than content
+- Bad, because users without GitHub access cannot see detailed changelogs
+- Bad, because breaks offline changelog access (mitigated by git tags and package.json version)
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- CHANGELOG.md file contains redirect message with GitHub Releases URL
+- semantic-release creates GitHub Releases with comprehensive release notes
+- No manual CHANGELOG.md maintenance occurs in subsequent releases
+- Documentation updated to reference GitHub Releases as changelog source
+- New contributors directed to GitHub Releases rather than CHANGELOG.md
+- Release process validates that GitHub Releases are created automatically
+- Historical changelog content remains accessible in git history
+
+## Pros and Cons of the Options
+
+### Use CHANGELOG.md as redirect to GitHub Releases page
+
+Replace CHANGELOG.md with a redirect message pointing to GitHub Releases.
+
+- Good, because maintains file presence for backward compatibility
+- Good, because clearly directs users to authoritative source
+- Good, because eliminates duplicate maintenance
+- Good, because simple and clear implementation
+- Good, because preserves historical changelog in git history
+- Neutral, because requires GitHub access for detailed changelog
+- Bad, because CHANGELOG.md no longer contains actual changelog content
+
+### Continue maintaining both manual CHANGELOG.md and GitHub Releases
+
+Keep manual CHANGELOG.md updated alongside automated GitHub Releases.
+
+- Good, because provides maximum accessibility
+- Good, because maintains traditional expectations
+- Neutral, because offers redundancy
+- Bad, because duplicates maintenance effort significantly
+- Bad, because creates synchronization risk
+- Bad, because negates benefits of semantic-release automation
+- Bad, because requires manual discipline for every release
+- Bad, because potential for inconsistency between sources
+
+### Completely remove CHANGELOG.md file
+
+Delete CHANGELOG.md entirely and rely solely on GitHub Releases.
+
+- Good, because completely eliminates duplicate maintenance
+- Good, because clearly establishes GitHub Releases as source of truth
+- Good, because most direct implementation of semantic-release pattern
+- Neutral, because follows some modern project conventions
+- Bad, because breaks tooling that expects CHANGELOG.md presence
+- Bad, because unexpected for users accustomed to changelog files
+- Bad, because removes clear signposting to release information
+- Bad, because loses historical changelog from repository view
+
+### Keep manual CHANGELOG.md and disable semantic-release changelog generation
+
+Maintain manual CHANGELOG.md as primary changelog and disable automated generation.
+
+- Good, because provides full control over changelog content
+- Good, because maintains traditional changelog maintenance
+- Neutral, because keeps changelog in repository
+- Bad, because foregoes semantic-release automation benefits
+- Bad, because requires manual discipline for every release
+- Bad, because prone to omissions and inconsistencies
+- Bad, because creates additional maintenance burden
+- Bad, because doesn't leverage conventional commits for changelog
+- Bad, because prevents automated release notes generation
+
+## More Information
+
+This decision builds upon ADR 006 "Semantic Release for Automated Publishing" by completing the transition to fully automated release management. The manual CHANGELOG.md served the project well during the initial development phase, but semantic-release provides superior automation and consistency.
+
+The CHANGELOG.md redirect will contain:
+
+```markdown
+# Changelog
+
+This project uses automated release management via semantic-release.
+
+For detailed release notes and changelog information, please see:
+**[GitHub Releases](https://github.com/voder-ai/eslint-plugin-traceability/releases)**
+
+Each release includes:
+
+- Detailed change descriptions
+- Commit references
+- Breaking changes (if any)
+- Migration notes (when applicable)
+
+Historical changelog entries prior to automated release management are preserved in this file's git history.
+```
+
+GitHub Releases will automatically include:
+
+- Semantic version number from conventional commits
+- Release date and tag reference
+- Categorized changes (Features, Bug Fixes, Breaking Changes)
+- Individual commit references with links
+- Contributor information
+- Generated from conventional commit messages
+
+semantic-release configuration ensures:
+
+- `@semantic-release/release-notes-generator` creates formatted release notes
+- `@semantic-release/github` publishes releases to GitHub
+- All commits since last release are analyzed and categorized
+- Release notes follow consistent format across all releases
+
+This decision should be re-evaluated if:
+
+- Significant user base requires offline changelog access
+- Project moves away from GitHub hosting
+- semantic-release becomes unmaintained or problematic
+- Tooling dependencies emerge that require traditional CHANGELOG.md
+- Community feedback strongly favors manual changelog maintenance
+
+Related decisions:
+
+- ADR 006: Semantic Release for Automated Publishing (establishes automated release management)
+- ADR 004: Automated Version Bumping for CI/CD (superseded by ADR 006)
+
+Related resources:
+
+- [semantic-release GitHub Plugin](https://github.com/semantic-release/github)
+- [GitHub Releases Documentation](https://docs.github.com/en/repositories/releasing-projects-on-github)
+- [Keep a Changelog](https://keepachangelog.com/) - traditional approach being deprecated

package/docs/decisions/008-ci-audit-flags.accepted.md

@@ -0,0 +1,60 @@
+# ADR-008: Standardize npm audit flags in CI and local verification
+
+## Status
+
+Accepted
+
+## Context
+
+Newer versions of `npm` emit a configuration warning when the `--production` flag is used with `npm audit`:
+
+> npm WARN config production Use `--omit=dev` instead.
+
+Our CI/CD pipeline and local `ci-verify:full` script were invoking:
+
+- `npm audit --production --audit-level=high` in the GitHub Actions workflow
+- `npm audit --production --audit-level=high` inside the `ci-verify:full` npm script
+
+This produced noisy warnings during both local verification and CI runs, even though the intent was simply to exclude development dependencies from the production-focused audit.
+
+## Decision
+
+We will standardize on the modern, npm-recommended flag set for production-focused audits:
+
+- Use `npm audit --omit=dev --audit-level=high` instead of `npm audit --production --audit-level=high`.
+
+Concretely:
+
+1. **GitHub Actions CI/CD workflow**
+   - In `.github/workflows/ci-cd.yml`, the "Run production security audit" step now runs:
+     - `npm audit --omit=dev --audit-level=high`
+
+2. **Local CI verification script**
+   - In `package.json`, the `ci-verify:full` script now runs:
+     - `npm audit --omit=dev --audit-level=high`
+
+3. **CI audit helper script**
+   - `scripts/ci-audit.js` continues to run `npm audit --json` to capture a complete machine-readable audit report for CI artifacts. The JSDoc description was updated to avoid hard-coding specific flag combinations in documentation, keeping behavior and documentation loosely coupled.
+
+## Rationale
+
+- **Align with npm guidance**: Using `--omit=dev` is the officially recommended modern way to exclude development dependencies from production operations. This avoids the recurring `npm WARN config production` warning.
+- **Consistency between local and CI behavior**: Both the GitHub Actions workflow and the local `ci-verify:full` script now use the same `npm audit` flags for production-focused audits, ensuring developers see the same behavior locally that CI enforces.
+- **Separation of concerns**:
+  - Production-focused audits use `--omit=dev --audit-level=high` to focus on runtime dependencies and fail the pipeline if high-severity issues are detected.
+  - Dev-dependency audits are handled separately via `npm run audit:dev-high` (which is already wired into both `ci-verify:full` and the CI workflow) and through our `dry-aged-deps`-backed safety checks.
+- **Noise reduction**: Removing the `--production` flag eliminates unnecessary warnings from CI logs, making real problems easier to spot.
+
+## Consequences
+
+- **Positive**:
+  - CI logs are cleaner, with no spurious `npm WARN config production` messages.
+  - The project follows current npm best practices for production audits.
+  - Local and CI verification remain in sync, preventing "works locally but fails in CI" discrepancies for security audits.
+
+- **Neutral/Expected**:
+  - The effective set of audited packages for the production-focused audit remains equivalent to what we intended with `--production`: runtime (non-dev) dependencies only.
+  - Our separate dev-dependency audit and `dry-aged-deps` processes remain unchanged.
+
+- **Future work**:
+  - If npm introduces further changes to `npm audit` flags or behavior, we will revisit this ADR and update the workflow and scripts accordingly.

package/docs/decisions/009-security-focused-lint-rules.accepted.md

@@ -0,0 +1,64 @@
+---
+status: "accepted"
+date: 2025-11-23
+decision-makers: [Development Team]
+consulted:
+  [ESLint Documentation, eslint-plugin-security, Node.js Security Guidance]
+informed: [All Contributors]
+---
+
+# 009-Security-Focused Lint Rules
+
+## Context and Problem Statement
+
+This project already has strong baseline linting focused on maintainability (complexity, max-lines, no-magic-numbers, max-params). However, a few classes of security-relevant issues are not explicitly guarded by lint rules yet, such as dynamic code evaluation, construction of regular expressions from untrusted input, and accidental use of insecure randomness APIs.
+
+While this plugin is primarily an ESLint rule set and maintenance CLI (not a network service), adding lightweight security-focused rules will help catch risky patterns early, especially in helper scripts and potential future extensions.
+
+## Decision
+
+We will tighten the ESLint configuration by enabling a **minimal set of built-in security-relevant rules** that are low-noise for this codebase and do not require additional dependencies:
+
+- `no-eval`: disallow use of `eval()` entirely.
+- `no-implied-eval`: disallow string forms of `setTimeout`, `setInterval`, and `Function` constructors.
+- `no-new-func`: disallow `new Function(...)`.
+- `no-new-wrappers`: disallow boxed primitives (`new String`, `new Number`, `new Boolean`).
+
+These rules will be enabled for all TypeScript and JavaScript source files (not tests) with severity `error`.
+
+## Rationale
+
+- These rules are part of core ESLint and require **no new plugins**.
+- They directly guard against dynamic code evaluation and other patterns that frequently lead to security vulnerabilities when combined with untrusted input.
+- The current codebase already avoids these patterns, so enabling the rules should have **zero or near-zero violations**, keeping the ratcheting impact small.
+- By starting with a small, well-justified subset, we avoid overwhelming contributors while still improving the security posture.
+
+## Consequences
+
+- **Positive**
+  - Immediate feedback in local development and CI if unsafe patterns such as `eval` or `new Function` are introduced.
+  - No additional dependency or configuration complexity.
+  - Aligns the project with common Node.js security linting baselines.
+
+- **Negative / Trade-offs**
+  - Very rare legitimate uses of `new Function` or similar patterns would require design reconsideration or narrowly scoped disable comments.
+  - Contributors must be aware of these rules and avoid dynamic evaluation patterns.
+
+## Implementation
+
+- Update `eslint.config.js` TypeScript and JavaScript rule blocks to include:
+  - `"no-eval": "error"`
+  - `"no-implied-eval": "error"`
+  - `"no-new-func": "error"`
+  - `"no-new-wrappers": "error"`
+- Run `npm run lint` and adjust any unexpected violations (none expected in the current codebase).
+
+## Validation
+
+- `npm run lint -- --max-warnings=0` passes with the new rules enabled.
+- CI (`npm run ci-verify:full`) passes without additional changes.
+- Future attempts to introduce `eval`, `new Function`, or similar patterns fail linting locally and in CI.
+
+## Future Work
+
+If the project grows to include more complex parsing, templating, or data handling, we may consider introducing additional security-focused rules via dedicated plugins (e.g., `eslint-plugin-security`) following the same ratcheting approach: start with a small, low-noise subset, validate impact, and expand incrementally.