eslint-plugin-traceability 1.1.0 → 1.1.2

package/cli-integration.js

@@ -1,103 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI integration tests script for ESLint Traceability Plugin
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
- */
-const { spawnSync } = require("child_process");
-const path = require("path");
-
-// Resolve the ESLint CLI binary and configuration path
-const eslintPkgDir = path.dirname(require.resolve("eslint/package.json"));
-const eslintCliPath = path.join(eslintPkgDir, "bin", "eslint.js");
-const configPath = path.resolve(__dirname, "eslint.config.js");
-
-// Define CLI integration test scenarios
-const tests = [
-  {
-    name: "reports error when @story annotation is missing",
-    code: "function foo() {}",
-    rule: "traceability/require-story-annotation:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "does not report error when @story annotation is present",
-    code: `/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- */
-function foo() {}`,
-    rule: "traceability/require-story-annotation:error",
-    expectedStatus: 0,
-  },
-  {
-    name: "reports error when @req annotation is missing",
-    code: "function bar() {}",
-    rule: "traceability/require-req-annotation:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "reports error when @story annotation uses path traversal and @req annotation uses path traversal",
-    code: `/**
- * @story ../docs/stories/invalid.story.md
- * @req ../docs/requirements/REQ-INVALID.md
- */
-function bar() {}`,
-    rule: "traceability/valid-req-reference:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "reports error when @story annotation uses absolute path and @req annotation uses absolute path",
-    code: `/**
- * @story /absolute/path/to/story.story.md
- * @req /etc/passwd
- */
-function baz() {}`,
-    rule: "traceability/valid-req-reference:error",
-    expectedStatus: 1,
-  },
-];
-
-/**
- * Run ESLint CLI with given code and rule override
- * @param {string} code Source code to lint via stdin
- * @param {string} rule ESLint rule override e.g. "traceability/require-story-annotation:error"
- * @returns {object} Result of spawnSync call
- */
-function runEslint(code, rule) {
-  const args = [
-    "--no-config-lookup",
-    "--config",
-    configPath,
-    "--stdin",
-    "--stdin-filename",
-    "foo.js",
-    "--rule",
-    "no-unused-vars:off",
-    "--rule",
-    rule,
-  ];
-  return spawnSync(process.execPath, [eslintCliPath, ...args], {
-    encoding: "utf-8",
-    input: code,
-  });
-}
-
-// Execute tests and report results
-let failures = 0;
-tests.forEach((test) => {
-  const result = runEslint(test.code, test.rule);
-  const passed = result.status === test.expectedStatus;
-  if (passed) {
-    console.log(`✓ ${test.name}`);
-  } else {
-    console.error(`✗ ${test.name}`);
-    console.error(
-      `  Expected exit code ${test.expectedStatus}, got ${result.status}`,
-    );
-    if (result.stdout) console.error(`  stdout: ${result.stdout}`);
-    if (result.stderr) console.error(`  stderr: ${result.stderr}`);
-    failures++;
-  }
-});
-
-process.exit(failures > 0 ? 1 : 0);

package/docs/cli-integration.md

@@ -1,105 +0,0 @@
-# CLI Integration Script Documentation
-
-This document provides detailed information about the `cli-integration.js` script, which runs end-to-end CLI integration tests for the `eslint-plugin-traceability` plugin.
-
-Story: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md  
-Requirement: REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
-
-## Overview
-
-The `cli-integration.js` script automates tests that invoke the ESLint CLI with the plugin configured, verifying that rule errors are reported (or not) as expected when code is passed via `stdin`.
-
-It uses Node.js `child_process.spawnSync` to:
-
-- Disable default ESLint config resolution
-- Load the plugin via `eslint.config.js` flat config
-- Pass code and rule settings via `--stdin` and `--rule` flags
-
-## Tests Implemented
-
-The script defines an array of test scenarios, each with:
-
-- **name**: A descriptive test name
-- **code**: A string containing JavaScript code to lint
-- **rule**: An ESLint rule override specifying severity
-- **expectedStatus**: The expected exit code (0 or 1)
-
-Current test scenarios:
-
-1. `reports error when @story annotation is missing`
-   - Code: `function foo() {}`
-   - Rule: `traceability/require-story-annotation:error`
-   - Expected exit code: 1 (error reported)
-
-2. `does not report error when @story annotation is present`
-
-   ```js
-   /**
-    * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    */
-   function foo() {}
-   ```
-
-   - Rule: `traceability/require-story-annotation:error`
-   - Expected exit code: 0 (no error)
-
-3. `reports error when @req annotation is missing`
-   - Code: `function bar() {}`
-   - Rule: `traceability/valid-req-reference:error`
-   - Expected exit code: 1 (error reported)
-
-4. `reports error when @req annotation uses path traversal`
-
-   ```js
-   /**
-    * @req ../docs/requirements/REQ-INVALID.md
-    */
-   function bar() {}
-   ```
-
-   - Rule: `traceability/valid-req-reference:error`
-   - Expected exit code: 1 (error reported)
-
-5. `reports error when @req annotation uses absolute path`
-
-   ```js
-   /**
-    * @req /etc/passwd
-    */
-   function baz() {}
-   ```
-
-   - Rule: `traceability/valid-req-reference:error`
-   - Expected exit code: 1 (error reported)
-
-## Usage
-
-Note: The script lives at the project root.
-
-```bash
-# Run CLI integration tests
-node ./cli-integration.js
-```
-
-## Integration into CI
-
-The CI workflow (`.github/workflows/ci.yml`) includes a separate `integration-tests` job that runs:
-
-```yaml
-jobs:
-  integration-tests:
-    needs: quality-checks
-    run: node cli-integration.js
-```
-
-This ensures that CLI-level behavior is verified on all supported Node.js versions.
-
-## Extending Tests
-
-To add new CLI integration scenarios:
-
-1. Open `cli-integration.js`.
-2. Append a new object to the `tests` array with the desired `name`, `code`, `rule`, and `expectedStatus`.
-3. Run `node cli-integration.js` locally to verify.
-
-Ensure that any new scenarios have clear test names and cover distinct rule behaviors.

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 at the `error` level:
-
-- `traceability/require-story-annotation`
-- `traceability/require-req-annotation`
-- `traceability/require-branch-annotation`
-- `traceability/valid-annotation-format`
-- `traceability/valid-story-reference`
-- `traceability/valid-req-reference`
-
-## Strict Preset
-
-Use the **strict** preset to enforce the same core rules, with potential future enhancements for stricter policies.
-
-```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)

package/docs/decisions/001-typescript-for-eslint-plugin.accepted.md

@@ -1,111 +0,0 @@
----
-status: "accepted"
-date: 2025-11-15
-decision-makers: [Development Team]
-consulted: [ESLint Community Best Practices, TypeScript ESLint Documentation]
-informed: [Project Stakeholders, Future Contributors]
----
-
-# Use TypeScript for ESLint Plugin Development
-
-## Context and Problem Statement
-
-When developing an ESLint plugin that validates code traceability annotations (@story and @req comments), we need to choose the implementation language. The plugin will perform complex Abstract Syntax Tree (AST) manipulation to analyze JavaScript/TypeScript code and validate annotation compliance. The choice between JavaScript and TypeScript affects development experience, maintainability, error prevention, and integration with the broader ESLint ecosystem.
-
-## Decision Drivers
-
-- Need for type safety when working with complex AST structures and ESLint Rule API
-- Developer experience and IDE support for plugin development
-- Integration with modern ESLint tooling and TypeScript ecosystem
-- Error prevention during AST manipulation and rule configuration
-- Long-term maintainability of the plugin codebase
-- Alignment with ESLint plugin development best practices
-- Support for advanced TypeScript-aware parsing when needed
-
-## Considered Options
-
-- TypeScript with full type definitions
-- JavaScript with JSDoc type annotations
-- Plain JavaScript without type annotations
-
-## Decision Outcome
-
-Chosen option: "TypeScript with full type definitions", because it provides the strongest type safety for complex AST manipulation, offers the best developer experience through IDE integration, aligns with modern ESLint plugin development practices, and enables seamless integration with @typescript-eslint utilities.
-
-### Consequences
-
-- Good, because TypeScript prevents runtime errors from malformed AST access patterns
-- Good, because IDE autocompletion and IntelliSense improve development velocity
-- Good, because type definitions serve as living documentation for rule APIs
-- Good, because integration with @typescript-eslint/utils provides advanced parsing capabilities
-- Good, because refactoring becomes safer as the plugin grows in complexity
-- Good, because follows established patterns in the ESLint ecosystem
-- Bad, because requires additional build step for TypeScript compilation
-- Bad, because slightly increases initial setup complexity
-- Bad, because may have learning curve for developers unfamiliar with TypeScript
-
-### Confirmation
-
-Implementation compliance will be confirmed through:
-
-- TypeScript compilation passes without errors in CI/CD pipeline
-- All plugin source files use .ts extension
-- package.json includes TypeScript as development dependency
-- tsconfig.json configured for ESLint plugin development
-- Use of @typescript-eslint/utils for AST manipulation where appropriate
-- Type definitions for all rule configurations and options
-
-## Pros and Cons of the Options
-
-### TypeScript with full type definitions
-
-TypeScript provides compile-time type checking, excellent IDE support, and strong integration with ESLint tooling ecosystem.
-
-- Good, because prevents common AST manipulation errors at compile time
-- Good, because provides excellent IDE autocompletion for ESLint Rule API
-- Good, because enables type-safe rule configuration and options validation
-- Good, because integrates seamlessly with @typescript-eslint/utils
-- Good, because self-documents code through type annotations
-- Good, because supports advanced refactoring capabilities
-- Good, because aligns with modern ESLint plugin development practices
-- Neutral, because requires TypeScript knowledge from contributors
-- Bad, because adds compilation step to development workflow
-- Bad, because increases initial project setup complexity
-
-### JavaScript with JSDoc type annotations
-
-JavaScript with JSDoc comments provides some type hints while maintaining simpler build process.
-
-- Good, because no additional build step required
-- Good, because familiar to JavaScript-only developers
-- Good, because provides basic type hints through comments
-- Neutral, because some IDE support for JSDoc types
-- Bad, because no compile-time error checking
-- Bad, because JSDoc types are not enforced or validated
-- Bad, because limited integration with @typescript-eslint type definitions
-- Bad, because refactoring support is significantly weaker
-- Bad, because AST manipulation errors only discovered at runtime
-
-### Plain JavaScript without type annotations
-
-Pure JavaScript implementation with no type system support.
-
-- Good, because simplest possible setup
-- Good, because no build step required
-- Good, because no TypeScript learning curve
-- Bad, because no type safety for complex AST manipulation
-- Bad, because no IDE autocompletion for ESLint APIs
-- Bad, because all errors discovered at runtime during testing
-- Bad, because difficult to maintain as complexity grows
-- Bad, because no integration benefits with TypeScript ecosystem
-- Bad, because poor refactoring support
-
-## More Information
-
-This decision aligns with REQ-TYPESCRIPT in story 001.0-DEV-PLUGIN-SETUP. The implementation should use @typescript-eslint/utils for AST parsing utilities and follow TypeScript ESLint plugin development patterns. The decision should be re-evaluated if TypeScript compilation becomes a significant bottleneck or if the team expertise changes significantly.
-
-Related resources:
-
-- [ESLint Plugin Development Guide](https://eslint.org/docs/latest/extend/plugins)
-- [@typescript-eslint/utils Documentation](https://typescript-eslint.io/packages/utils/)
-- [TypeScript ESLint Plugin Examples](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin/src/rules)

package/docs/decisions/002-jest-for-eslint-testing.accepted.md

@@ -1,137 +0,0 @@
----
-status: "accepted"
-date: 2025-11-15
-decision-makers: [Development Team]
-consulted:
-  [
-    ESLint Community Best Practices,
-    Jest Documentation,
-    Vitest Documentation,
-    TypeScript ESLint Testing Patterns,
-  ]
-informed: [Project Stakeholders, Future Contributors]
----
-
-# Use Jest for ESLint Plugin Testing
-
-## Context and Problem Statement
-
-When developing an ESLint plugin in TypeScript that outputs CommonJS modules, we need to choose a testing framework for validating ESLint rules. The plugin will use ESLint's RuleTester for rule validation and needs to test complex AST manipulation logic. The choice of testing framework affects development experience, compatibility with ESLint tooling, and alignment with ecosystem practices, particularly given the CommonJS output requirement and ESLint-specific testing patterns.
-
-## Decision Drivers
-
-- Compatibility with ESLint's RuleTester and rule testing patterns
-- Support for CommonJS module testing (plugin output format)
-- Integration with TypeScript source code testing
-- Alignment with ESLint plugin development ecosystem practices
-- Developer experience for writing and debugging tests
-- Performance and reliability of test execution
-- Support for ESLint-specific testing utilities and patterns
-- Community adoption and long-term maintenance
-
-## Considered Options
-
-- Jest with TypeScript support
-- Vitest with CommonJS configuration
-- Node.js built-in test runner with TypeScript
-
-## Decision Outcome
-
-Chosen option: "Jest with TypeScript support", because it provides native CommonJS support essential for ESLint plugin testing, seamless integration with ESLint's RuleTester, follows established patterns in the ESLint ecosystem, and offers superior tooling for ESLint rule development without requiring complex configuration workarounds.
-
-### Consequences
-
-- Good, because Jest works natively with CommonJS modules (no configuration needed)
-- Good, because ESLint's RuleTester integrates seamlessly with Jest
-- Good, because follows patterns used by @typescript-eslint and most ESLint plugins
-- Good, because excellent TypeScript support through ts-jest
-- Good, because mature ecosystem with extensive ESLint testing examples
-- Good, because built-in mocking capabilities useful for file system operations
-- Good, because snapshot testing can validate error message formats
-- Bad, because Jest is slightly heavier than newer alternatives
-- Bad, because not as fast as Vitest for some use cases
-- Neutral, because requires ts-jest dependency for TypeScript support
-
-### Confirmation
-
-Implementation compliance will be confirmed through:
-
-- Jest configuration properly set up with ts-jest transformer
-- ESLint RuleTester tests run successfully without module resolution errors
-- All tests pass in CI/CD pipeline using Jest
-- package.json scripts include Jest-based testing commands
-- Test files use Jest APIs and follow Jest patterns
-- TypeScript source files can be tested directly without compilation issues
-
-## Pros and Cons of the Options
-
-### Jest with TypeScript support
-
-Jest is the most widely used testing framework in the ESLint ecosystem with mature TypeScript integration.
-
-- Good, because native CommonJS support without configuration
-- Good, because ESLint's RuleTester designed to work with Jest
-- Good, because extensive use in @typescript-eslint project provides proven patterns
-- Good, because excellent TypeScript support via ts-jest
-- Good, because mature snapshot testing for validating rule outputs
-- Good, because built-in mocking for testing file system operations
-- Good, because extensive community knowledge and examples
-- Good, because comprehensive assertion library and testing utilities
-- Neutral, because larger bundle size than alternatives
-- Neutral, because slower startup than Vitest
-- Bad, because not as modern as newer testing frameworks
-
-### Vitest with CommonJS configuration
-
-Vitest is a modern testing framework built on Vite with fast execution but requires configuration for CommonJS.
-
-- Good, because very fast test execution and hot reloading
-- Good, because modern API and excellent DX
-- Good, because good TypeScript support out of the box
-- Good, because lighter weight than Jest
-- Neutral, because growing but smaller community than Jest
-- Bad, because requires complex configuration for CommonJS compatibility
-- Bad, because ESLint RuleTester integration not well-documented
-- Bad, because fewer examples in ESLint plugin development
-- Bad, because potential issues with CommonJS module transformation
-- Bad, because ESM-first design conflicts with CommonJS requirement
-
-### Node.js built-in test runner with TypeScript
-
-Node.js native test runner provides minimal testing without external dependencies.
-
-- Good, because no external testing dependencies
-- Good, because fast startup and execution
-- Good, because growing support in Node.js ecosystem
-- Neutral, because basic feature set may be sufficient for simple tests
-- Bad, because no built-in TypeScript support (requires compilation)
-- Bad, because no established patterns for ESLint rule testing
-- Bad, because limited assertion library (requires additional dependencies)
-- Bad, because no built-in mocking capabilities
-- Bad, because minimal tooling and IDE integration
-- Bad, because ESLint RuleTester compatibility unknown
-
-## More Information
-
-This decision supports REQ-TEST-SETUP in story 001.0-DEV-PLUGIN-SETUP. The implementation should use ts-jest for TypeScript compilation and follow patterns established by @typescript-eslint project. ESLint's RuleTester should be the primary tool for rule validation testing.
-
-Key implementation considerations:
-
-- Use ts-jest transformer for TypeScript source testing
-- Configure Jest to handle both source TypeScript and compiled CommonJS
-- Follow ESLint RuleTester patterns for rule validation
-- Include snapshot testing for error message validation
-- Set up proper mocking for file system operations
-
-This decision should be re-evaluated if:
-
-- ESLint ecosystem moves away from Jest as standard
-- CommonJS requirement changes for ESLint plugins
-- Vitest significantly improves CommonJS support
-- Team expertise with Jest becomes insufficient
-
-Related resources:
-
-- [ESLint RuleTester Documentation](https://eslint.org/docs/latest/integrate/nodejs-api#ruletester)
-- [@typescript-eslint Testing Patterns](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin/tests)
-- [Jest with TypeScript Guide](https://jestjs.io/docs/getting-started#using-typescript)