eslint-plugin-traceability 1.0.0

package/docs/cli-integration.md

@@ -0,0 +1,103 @@
+# 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
+
+```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

@@ -0,0 +1,38 @@
+# 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/decisions/001-typescript-for-eslint-plugin.accepted.md

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

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

package/docs/decisions/003-code-quality-ratcheting-plan.md

@@ -0,0 +1,48 @@
+---
+status: "accepted"
+date: 2025-11-16
+decision-makers: [Development Team]
+consulted: [Implementation Plan, ESLint Documentation]
+informed: [All Contributors]
+---
+
+# 003-Code Quality Ratcheting Plan
+
+## Context and Decision Drivers
+
+The project currently enforces maintainability through ESLint `max-lines-per-function` and `max-lines` rules with thresholds set to 200 lines/function and 1000 lines/file. These loose thresholds present technical debt and allow overly large functions and files, which can hinder readability, maintainability, and increase complexity over time.
+
+## Considered Options
+
+1. Adopt strict industry-standard thresholds immediately (e.g., 100 lines/function, 500 lines/file).
+2. Maintain the current loose thresholds indefinitely.
+3. Implement an incremental ratcheting plan to gradually reduce thresholds over multiple sprints.
+
+## Decision Outcome
+
+We will implement option 3: an incremental ratcheting plan to gradually reduce the ESLint thresholds:
+
+- **Sprint 0 (Now)**: Reduce `max-lines-per-function` to 150 and `max-lines` to 800.
+- **Sprint 2 (Completed 2025-11-16)**: Reduce `max-lines-per-function` to 120 and `max-lines` to 600.
+- **Sprint 4**: Reduce `max-lines-per-function` to 100 and `max-lines` to 500.
+
+Automation:
+
+- Update the ESLint configuration to enforce the new thresholds immediately.
+- Configure the CI pipeline to fail on any new violations of these rules.
+- Document the ratcheting schedule in this ADR and revisit the plan at each milestone.
+
+## Consequences
+
+- Ensures maintainability improves in manageable increments, reducing developer overhead per sprint.
+- Provides clear visibility into the schedule and expectations for code size reductions.
+- Allows refactoring efforts to be planned and executed incrementally, avoiding large-scale rewrites.
+- Guarantees continuous improvement by automating enforcement in CI.
+
+## Future Review
+
+At the end of each milestone sprint, the team will:
+
+- Review existing violations.
+- Refactor code to comply with the new thresholds.
+- Update this ADR if any adjustments to the schedule are required.