eslint-plugin-traceability 1.8.0 → 1.8.1

package/user-docs/eslint-9-setup-guide.md

@@ -28,6 +28,9 @@ npm install --save-dev eslint@^9.39.1
 # Recommended configurations
 npm install --save-dev @eslint/js@^9.39.1
 
+# Traceability plugin
+npm install --save-dev eslint-plugin-traceability@^1.0.0
+
 # For TypeScript projects
 npm install --save-dev @typescript-eslint/parser@^8.0.0
 npm install --save-dev @typescript-eslint/utils@^8.0.0
@@ -67,13 +70,48 @@ export default [
 
 ### 4. Enable Traceability Plugin
 
-To integrate the traceability plugin, update your `eslint.config.js` to include its recommended configuration:
+To integrate the traceability plugin with its **recommended** preset, update your `eslint.config.js`:
+
+```javascript
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
+];
+```
+
+To use the **strict** preset instead:
 
 ```javascript
 import js from "@eslint/js";
 import traceability from "eslint-plugin-traceability";
 
-export default [js.configs.recommended, traceability.configs.recommended];
+export default [
+  js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.strict,
+];
+```
+
+Note: The `traceability.configs.recommended` and `traceability.configs.strict` presets define rule severities only. They expect the plugin to be registered in a preceding flat-config object via:
+
+```javascript
+{
+  plugins: {
+    traceability,
+  },
+}
 ```
 
 ## Configuration File Format
@@ -137,9 +175,16 @@ Both forms are supported by ESLint 9 as long as the file extension and `package.
 ```javascript
 // eslint.config.js
 import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.js", "**/*.mjs"],
     languageOptions: {
@@ -163,9 +208,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.ts", "**/*.tsx"],
     languageOptions: {
@@ -197,9 +249,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.{js,jsx,ts,tsx}"],
     languageOptions: {
@@ -282,9 +341,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     // Lint all packages in a monorepo/workspace
     files: ["packages/*/src/**/*.{js,ts,tsx}"],
@@ -479,9 +545,16 @@ Solution: Use combined file patterns or separate override blocks, and import the
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.{js,jsx,ts,tsx}"],
     languageOptions: {
@@ -512,6 +585,7 @@ Here's a complete working configuration for a TypeScript ESLint plugin project:
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 // Conditional plugin loading (for plugin development)
 let plugin;
@@ -524,6 +598,15 @@ try {
 
 export default [
   js.configs.recommended,
+  {
+    // Register the traceability plugin for subsequent presets/rules
+    plugins: {
+      traceability,
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
+    },
+  },
+  // Apply the recommended preset for the published plugin
+  ...traceability.configs.recommended,
   {
     // Node.js config files (CommonJS)
     files: ["*.config.js", "*.config.mjs", "jest.config.js"],
@@ -554,7 +637,7 @@ export default [
       },
     },
     plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
     },
     rules: {
       "@typescript-eslint/no-unused-vars": "error",
@@ -568,7 +651,7 @@ export default [
       sourceType: "module",
     },
     plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
     },
   },
   {
@@ -621,6 +704,7 @@ export default [
     "@typescript-eslint/parser": "^8.46.4",
     "@typescript-eslint/utils": "^8.46.4",
     "eslint": "^9.39.1",
+    "eslint-plugin-traceability": "^1.0.0",
     "typescript": "^5.9.3"
   }
 }
@@ -635,5 +719,4 @@ export default [
 5. **Use file patterns** instead of CLI `--ext` flags
 6. **Structure as array of objects**, each targeting specific file types
 7. **Use `ignores`** instead of `.eslintignore` files
-
-This setup provides a solid foundation for ESLint 9 that works reliably across different project types and environments.
+8. **Register plugins explicitly** in flat config before spreading their presets

package/user-docs/migration-guide.md

@@ -57,6 +57,25 @@ function integrate() {}
 
 You **do not** need to change existing, single-story annotations that already use `@story` and `@req`. Migration to `@implements` is only recommended when a function or module genuinely implements requirements from more than one story file.
 
+#### Optional `prefer-implements-annotation` migration rule
+
+For teams that want to gradually migrate from `@story` + `@req` to `@implements`, the plugin provides an optional rule: `traceability/prefer-implements-annotation`.
+
+- This rule is **disabled by default** and is **not** included in any built-in presets.
+- You can enable it with any standard ESLint severity (`"off"`, `"warn"`, or `"error"`) in your config, for example:
+
+  ```js
+  // excerpt from eslint.config.js
+  {
+    rules: {
+      "traceability/prefer-implements-annotation": "warn",
+    },
+  }
+  ```
+
+- When enabled, it offers **conservative auto-fixes** that rewrite eligible `@story` + `@req` combinations into equivalent `@implements` lines, without attempting risky or ambiguous transformations.
+- Detailed behavior, limitations, and examples are documented in `docs/rules/prefer-implements-annotation.md`.
+
 #### When to keep `@story` + `@req`
 
 Keep your current annotations if:
@@ -130,10 +149,7 @@ You can introduce `@implements` gradually without breaking existing code:
 3. Run ESLint with `traceability/valid-annotation-format` and `traceability/valid-req-reference` enabled to confirm everything passes.
 4. Optionally, once you are comfortable, standardize on using `@implements` for multi-story integration functions while keeping `@story` + `@req` for simple, single-story code.
 
-For detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures), see:
-
-- Rule docs: [`docs/rules/valid-annotation-format.md`](../docs/rules/valid-annotation-format.md), [`docs/rules/valid-req-reference.md`](../docs/rules/valid-req-reference.md)
-- Story: [`docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md`](../docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md)
+For detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures), see the valid-annotation-format and valid-req-reference rule documentation and the multi-story support story in the project documentation.
 
 ## 4. Test and Validate
 

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.