eslint-plugin-traceability 1.8.0 → 1.8.2

package/docs/ci-cd-pipeline.md

@@ -1,224 +0,0 @@
-# CI/CD Pipeline and Continuous Deployment
-
-This document describes how continuous integration and continuous deployment are implemented for `eslint-plugin-traceability`, and how it relates to our architecture decisions.
-
-- Related ADRs:
-  - `docs/decisions/006-semantic-release-for-automated-publishing.accepted.md`
-  - `docs/decisions/007-github-releases-over-changelog.accepted.md`
-  - `docs/decisions/005-github-actions-validation-tooling.accepted.md`
-
-## Overview
-
-We use a **single unified GitHub Actions workflow** to run all quality checks and, on successful main-branch builds, to automatically publish new versions to npm and create GitHub Releases.
-
-- Workflow file: `.github/workflows/ci-cd.yml`
-- Workflow name: `CI/CD Pipeline`
-- Triggers:
-  - `push` to `main`
-  - `pull_request` targeting `main`
-  - Nightly `schedule` for dependency health checks
-
-There are no tag-based triggers and no manual `workflow_dispatch` jobs for releases. Publishing (when needed) always happens as part of the same workflow run that executes the quality gates.
-
-## Jobs
-
-### 1. `quality-and-deploy`
-
-Runs on:
-
-- Every `push` to `main`
-- Every `pull_request` targeting `main`
-
-Matrix:
-
-- Node `18.x`
-- Node `20.x`
-
-Key steps (in order):
-
-1. **Checkout & Node setup**
-   - `actions/checkout@v4` with full history (needed for semantic-release)
-   - `actions/setup-node@v4` with `cache: npm`
-
-2. **Script validation**
-   - `node scripts/validate-scripts-nonempty.js` ensures all npm scripts referenced by CI exist and are non-empty.
-
-3. **Install dependencies**
-   - `npm ci`
-
-4. **Full quality gate**
-   - `npm run ci-verify:full`
-   - This script is the canonical definition of our quality gates and is also used by the Husky pre-push hook.
-   - It runs, in order:
-     - `npm run check:traceability`
-     - `npm run safety:deps`
-     - `npm run audit:ci`
-     - `npm run build`
-     - `npm run type-check`
-     - `npm run lint-plugin-check`
-     - `npm run lint -- --max-warnings=0`
-     - `npm run duplication`
-     - `npm run test -- --coverage`
-     - `npm run format:check`
-     - `npm audit --omit=dev --audit-level=high`
-     - `npm run audit:dev-high`
-
-5. **Secret scanning**
-   - Only on Node `20.x` matrix entry: `npm run security:secrets` using secretlint.
-
-6. **Artifact upload**
-   - Always upload:
-     - `ci/dry-aged-deps.json`
-     - `ci/npm-audit.json`
-     - `scripts/traceability-report.md`
-     - `ci/` (Jest and audit artifacts)
-
-7. **Automated release (semantic-release)**
-
-   Conditional step:
-
-   ```yaml
-   if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix['node-version'] == '20.x' && success() }}
-   ```
-
-   - Runs `npx semantic-release` with:
-     - GitHub authentication via `GITHUB_TOKEN`
-     - npm authentication via `NPM_TOKEN`
-   - Configuration is in `.releaserc.json` and uses:
-     - `@semantic-release/commit-analyzer`
-     - `@semantic-release/release-notes-generator`
-     - `@semantic-release/changelog` (writes to `CHANGELOG.md` but we treat GitHub Releases as the user-facing source of truth per ADR 007)
-     - `@semantic-release/npm` (publishes to npm)
-     - `@semantic-release/github` (creates GitHub Releases)
-
-   Behavior:
-   - On each successful push to `main`, semantic-release:
-     - Analyzes commits since the last tag using **Conventional Commits** (see `docs/conventional-commits-guide.md`).
-     - Decides whether the release is `major`, `minor`, `patch`, or **no release**.
-     - If no relevant commits are found, it logs that no new release is needed and exits successfully.
-     - If a release is warranted:
-       - Publishes a new version to npm.
-       - Creates or updates `CHANGELOG.md`.
-       - Creates a Git tag and GitHub Release with generated notes.
-
-   - Safety behavior:
-     - If `NPM_TOKEN` is **not set**, the step logs a message and exits 0 with `new_release_published=false`.
-     - If semantic-release fails due to invalid npm token (`EINVALIDNPMTOKEN`) or OTP requirement (`EOTP`), the step logs a warning and exits 0, skipping publish but not failing CI.
-     - Any other semantic-release error fails the job.
-
-8. **Post-deployment smoke test**
-   - Runs only when semantic-release reports that a new release was published:
-
-   ```yaml
-   if: steps.semantic-release.outputs.new_release_published == 'true'
-   ```
-
-   - Executes:
-
-   ```bash
-   chmod +x scripts/smoke-test.sh
-   ./scripts/smoke-test.sh "${{ steps.semantic-release.outputs.new_release_version }}"
-   ```
-
-   - `scripts/smoke-test.sh`:
-     - For a published version: waits for the version to appear on npm, then
-       - Creates a temp project.
-       - Installs `eslint-plugin-traceability@<version>`.
-       - Verifies the plugin loads and the installed version matches.
-       - Runs a minimal ESLint config using the plugin to confirm it can be loaded.
-
-### 2. `dependency-health`
-
-Runs only on the nightly `schedule` event.
-
-- Checks out code and installs dependencies.
-- Runs `npm run audit:dev-high` to generate a JSON report of high-severity dev-only vulnerabilities.
-- Does **not** publish or run semantic-release.
-
-This job is intentionally isolated from the main quality-and-deploy path and has no effect on releases.
-
-## Continuous Deployment Behavior
-
-- Every push to `main` triggers the `quality-and-deploy` job on Node 18.x and 20.x.
-- The full quality gate (`ci-verify:full`) must pass on both Node versions.
-- If, and only if, the Node 20.x job on `main` succeeds and `NPM_TOKEN` is available, semantic-release is invoked.
-- semantic-release decides whether a new version is required based on commit messages:
-  - `feat` → minor version bump
-  - `fix` → patch bump
-  - `feat!` or `BREAKING CHANGE:` footer → major bump
-  - Other types (`docs`, `chore`, `refactor`, `test`, `ci`, etc.) do **not** trigger a release.
-- When a release is published, the smoke test runs immediately in the same workflow execution.
-
-There is no separate “publish only” workflow and no manual tagging step required to release. The pipeline from commit → quality gates → publish → smoke test is fully automated.
-
-## Local Workflow and Hooks
-
-To keep local development aligned with CI:
-
-- **Pre-commit** (`.husky/pre-commit`):
-  - Runs `npx lint-staged`, which executes Prettier and ESLint with `--fix` on staged files in `src/` and `tests/`.
-- **Pre-push** (`.husky/pre-push`):
-  - Runs `npm run ci-verify:full`.
-  - This mirrors the CI quality gate so that most issues are caught before code reaches GitHub.
-  - Secret scanning (`npm run security:secrets`) currently runs only in CI on the Node 20.x matrix entry and is not part of the pre-push hook, but it uses the same configuration so results stay consistent between local and CI.
-
-Local verification commands:
-
-- `npm run ci-verify:full`
-  - Runs the same broad, end-to-end quality gate used in CI (build, type-check, linting, duplication checks, full Jest test suite with coverage, audits, and formatting checks).
-  - This is the closest approximation to the CI pipeline and is what the pre-push hook enforces.
-
-- `npm run ci-verify:fast`
-  - Runs a **narrower, targeted subset** of checks focused on the rule and maintenance test suites.
-  - Uses Jest with:
-
-    ```bash
-    jest --testPathPatterns 'tests/(rules|maintenance)'
-    ```
-
-    to execute only tests whose paths match `tests/rules` or `tests/maintenance`.
-
-  - Intended as an **optional, faster pre-flight** command that contributors run manually to iterate quickly on rule changes and core maintenance behavior.
-  - Does **not** replace `ci-verify:full` and is **not** used by hooks or CI; it exists purely for faster local feedback.
-
-Developers should rely on:
-
-- `npm run ci-verify:full` for a full CI-equivalent check (and what will run on push via Husky).
-- `npm run ci-verify` or `npm run ci-verify:fast` for quicker, targeted local feedback loops when working on rules or maintenance logic.
-
-## How Semantic Versioning Is Determined
-
-semantic-release uses Conventional Commits (see `docs/conventional-commits-guide.md`) to infer version changes:
-
-- `feat:` → **minor** version bump.
-- `fix:` → **patch** version bump.
-- `feat!` or `fix!` (or any type with `!`) or a `BREAKING CHANGE:` footer → **major** version bump.
-- Other types (`docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`) → no release.
-
-Because releases are determined solely from commit history, it is important that all commits merged to `main` follow the documented Conventional Commits standard.
-
-## Supported Runtime and Tooling
-
-The pipeline runs against the following Node.js versions:
-
-- Node `18.x`
-- Node `20.x`
-
-The package itself declares:
-
-- `engines.node: ">=18.18.0"`
-- `peerDependencies.eslint: "^9.0.0"`
-
-User-facing docs are aligned with these constraints:
-
-- README “Prerequisites” section.
-- `user-docs/api-reference.md` "Supported runtime" line.
-
-## When Things Go Wrong
-
-- If **quality checks fail** (build, tests, lint, type-check, duplication, format, or audits), the workflow fails before any release attempt.
-- If semantic-release encounters a non-token, non-OTP error, the job fails and no release is published.
-- If `NPM_TOKEN` is missing or invalid, or if npm requires an OTP, the workflow succeeds but skips publishing; this is treated as a configuration issue rather than a code failure.
-- If the post-deployment smoke test fails, the job fails even though a package may have been published; this indicates an urgent regression in the published artifact.
-
-In all of these cases, the failing run is visible in the `CI/CD Pipeline` workflow on GitHub, and maintainers should fix the underlying issue before merging further changes to `main`.

package/docs/cli-integration.md

@@ -1,22 +0,0 @@
-# CLI Integration Guide
-
-Story: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md  
-Requirement: REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
-
-Integration tests for the ESLint CLI plugin are included in the Jest test suite under `tests/integration/cli-integration.test.ts`.
-
-## Running CLI Integration Tests
-
-To run only the CLI integration tests:
-
-```bash
-npm test -- tests/integration/cli-integration.test.ts
-```
-
-To run the full test suite:
-
-```bash
-npm test
-```
-
-These tests invoke the ESLint CLI with the plugin configured, verifying that rule errors are reported (or not) as expected when code is passed via `stdin`. Ensure your ESLint flat config (`eslint.config.js`) loads the plugin before running these tests.

package/docs/code-quality-refactor-opportunities-2025-12-03.md

@@ -1,78 +0,0 @@
-# Code Quality and Security Refactor Opportunities (2025-12-03)
-
-Created autonomously by voder.ai
-
-This note captures small, low-risk refactors that can be implemented incrementally to further improve maintainability and security without changing public behavior.
-
-## 1. Decompose maintenance CLI implementation
-
-**Files:**
-
-- `src/maintenance/cli.ts`
-
-**Motivation:**
-
-- `cli.ts` is one of the larger source files and currently owns argument parsing, flag normalization, subcommand dispatch, and user-facing messaging.
-- While it still passes `max-lines` and `max-lines-per-function` rules, splitting responsibilities would improve navigability.
-
-**Potential refactors:**
-
-- Extract a dedicated `src/maintenance/flags.ts` module responsible solely for:
-  - Defining the `CliFlags` shape and defaults.
-  - Implementing `applyFlag` / `parseFlags` behavior and validation.
-- Extract a `src/maintenance/commands.ts` module for the four subcommand handlers:
-  - `handleDetect`, `handleVerify`, `handleReport`, `handleUpdate`.
-  - Keep `runMaintenanceCli` as a small coordination layer that wires parsed arguments to these handlers.
-
-## 2. Narrow helper responsibilities in require-story helpers
-
-**Files:**
-
-- `src/rules/helpers/require-story-helpers.ts`
-- `src/rules/helpers/require-story-core.ts`
-
-**Motivation:**
-
-- These helpers concentrate multiple kinds of functionality: AST visitor construction, IO behavior, message construction, and small utility predicates.
-- Individual functions are reasonably sized, but the number of exported helpers makes the files dense.
-
-**Potential refactors:**
-
-- Introduce a dedicated `src/rules/helpers/require-story-io.ts` (already partially present) as the single place for reading and writing files in tests and rules.
-- Move purely structural helpers (e.g., small predicates, formatting helpers) into a `require-story-utils.ts`-style module so each file focuses on a single axis of responsibility.
-
-## 3. Revisit targeted ESLint suppressions
-
-**Files:**
-
-- `src/rules/helpers/valid-story-reference-helpers.ts` (single `no-unused-vars` suppression on a type-only parameter)
-- `src/rules/helpers/valid-annotation-options.ts` (single `max-params` suppression for a central option-normalization helper)
-- `tests/utils/ts-language-options.ts` (single `no-magic-numbers` suppression to allow ECMA version constants)
-
-**Motivation:**
-
-- Each suppression is currently justified and localized, but a small refactor could remove them entirely, simplifying the lint configuration.
-
-**Potential refactors:**
-
-- Replace the suppressed `max-params` helper with an options object parameter so callers pass a single argument while preserving type safety.
-- For the `no-unused-vars` case, explore using a `type`-only import or restructuring the function signature so all parameters are meaningfully consumed.
-- Extract ECMA version numbers into named constants in a small shared test utility module to avoid the need for a `no-magic-numbers` override.
-
-## 4. Optional: add slim wrappers for Story/Req detection utilities
-
-**Files:**
-
-- `src/utils/reqAnnotationDetection.ts`
-- `src/utils/annotation-checker.ts`
-
-**Motivation:**
-
-- These utilities are well-tested but contain a moderate amount of conditional logic for different AST node types.
-
-**Potential refactors:**
-
-- Introduce thin, strongly-typed wrapper functions for the most common call sites (e.g., “analyze function declaration for traceability annotations”) that hide some of the configuration detail from rule implementations.
-- This would make rule modules slightly smaller and more declarative, leaving the complex branching in a shared, well-tested location.
-
-These refactors should be tackled incrementally, one small change at a time, with existing Jest tests and ESLint rules acting as safety nets to ensure behavior remains unchanged.

package/docs/config-presets.md

@@ -1,38 +0,0 @@
-# Configuration Presets
-
-This document describes the built-in configuration presets provided by the `eslint-plugin-traceability` plugin.
-
-## Recommended Preset
-
-Use the **recommended** preset to enable the core traceability rule set with default settings.
-
-```javascript
-// eslint.config.js
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.recommended];
-```
-
-This preset enables the following rules with severities tuned for common usage (most at `error`, with `traceability/valid-annotation-format` at `warn` to reduce noise):
-
-- `traceability/require-story-annotation`: `error`
-- `traceability/require-req-annotation`: `error`
-- `traceability/require-branch-annotation`: `error`
-- `traceability/valid-annotation-format`: `warn`
-- `traceability/valid-story-reference`: `error`
-- `traceability/valid-req-reference`: `error`
-
-## Strict Preset
-
-Use the **strict** preset to enforce the same core rules, with potential future enhancements for stricter policies. Like the recommended preset, it configures `traceability/valid-annotation-format` as a `warn` to avoid excessive noise from format-only issues.
-
-```javascript
-// eslint.config.js
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.strict];
-```
-
-The **strict** preset currently mirrors the **recommended** rules, but may include additional constraints in future plugin versions.

package/docs/conventional-commits-guide.md

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