eslint-plugin-traceability 1.1.1 → 1.1.3

package/user-docs/api-reference.md

@@ -1,135 +0,0 @@
-# API Reference
-
-Created autonomously by [voder.ai](https://voder.ai).
-
-## Rules
-
-Each rule enforces traceability conventions in your code. Below is a summary of each rule exposed by this plugin.
-
-### traceability/require-story-annotation
-
-Description: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- */
-function initAuth() {
-  // authentication logic
-}
-```
-
-### traceability/require-req-annotation
-
-Description: Ensures every function declaration has an `@req` annotation in its JSDoc, linking to the specific requirement.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- */
-function initAuth() {
-  // authentication logic
-}
-```
-
-### traceability/require-branch-annotation
-
-Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-DETECTION
-if (error) {
-  handleError();
-}
-```
-
-### traceability/valid-annotation-format
-
-Description: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-/**
- * @story docs/stories/005.0-DEV-VALIDATION.story.md
- * @req REQ-FORMAT-VALIDATION
- */
-function example() {
-  // ...
-}
-```
-
-### traceability/valid-story-reference
-
-Description: Checks that the file paths in `@story` annotations point to existing story markdown files.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-/**
- * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md
- * @req REQ-STORY-EXISTS
- */
-function example() {
-  // ...
-}
-```
-
-### traceability/valid-req-reference
-
-Description: Verifies that the IDs used in `@req` annotations match known requirement identifiers.
-Options: None
-Default Severity: `error`
-Example:
-
-```javascript
-/**
- * @story docs/stories/007.0-DEV-REQ-REFERENCE.story.md
- * @req REQ-VALID-REFERENCE
- */
-function example() {
-  // ...
-}
-```
-
-## Configuration Presets
-
-The plugin provides two built-in presets for easy configuration:
-
-### recommended
-
-Enables the core traceability rules at the `error` level.
-Usage:
-
-```javascript
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.recommended];
-```
-
-### strict
-
-Currently mirrors the **recommended** preset, reserved for future stricter policies.
-Usage:
-
-```javascript
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.strict];
-```

package/user-docs/examples.md

@@ -1,73 +0,0 @@
-# Examples
-
-Created autonomously by [voder.ai](https://voder.ai).
-
-This document provides runnable examples demonstrating how to use the `eslint-plugin-traceability` plugin in real-world scenarios.
-
-## 1. ESLint Flat Config with Recommended Preset
-
-Create an ESLint config file (`eslint.config.js`) at your project root:
-
-```javascript
-// eslint.config.js
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.recommended];
-```
-
-Then run ESLint on your source files:
-
-```bash
-npx eslint "src/**/*.ts"
-```
-
-## 2. Using the Strict Preset
-
-If you want to enforce all traceability rules (strict mode), update your config:
-
-```javascript
-// eslint.config.js
-import js from "@eslint/js";
-import traceability from "eslint-plugin-traceability";
-
-export default [js.configs.recommended, traceability.configs.strict];
-```
-
-Run ESLint the same way:
-
-```bash
-npx eslint "src/**/*.js"
-```
-
-## 3. CLI Invocation Example
-
-You can use the plugin without a config file by specifying rules inline:
-
-```bash
-npx eslint --no-eslintrc \
-  --rule "traceability/require-story-annotation:error" \
-  --rule "traceability/require-req-annotation:error" \
-  sample.js
-```
-
-- `--no-eslintrc` tells ESLint to ignore user configs.
-- `--rule` options enable the traceability rules you need.
-
-Replace `sample.js` with your JavaScript or TypeScript file.
-
-## 4. Linting a Specific Directory
-
-Add an npm script in your `package.json`:
-
-```json
-"scripts": {
-  "lint:trace": "eslint \"src/**/*.{js,ts}\" --config eslint.config.js"
-}
-```
-
-Then run:
-
-```bash
-npm run lint:trace
-```

package/user-docs/migration-guide.md

@@ -1,71 +0,0 @@
-# Migration Guide from v0.x to v1.x
-
-Created autonomously by [voder.ai](https://voder.ai)
-
-This guide helps you migrate from versions 0.x of `eslint-plugin-traceability` to 1.x.
-
-## 1. Update Dependency
-
-Update your development dependency to the latest 1.x release:
-
-```bash
-npm install --save-dev eslint-plugin-traceability@^1.0.0
-```
-
-Or with Yarn:
-
-```bash
-yarn add --dev eslint-plugin-traceability@^1.0.0
-```
-
-## 2. ESLint Configuration Changes
-
-- Version 1.x uses ESLint v9 flat config by default. If you currently use `.eslintrc.js`, you can continue using it, but consider migrating to the new flat config format for future upgrades.
-- Update your ESLint config to load the plugin’s recommended settings:
-
-```js
-// eslint.config.js (ESLint v9 flat config)
-import traceability from "eslint-plugin-traceability";
-
-export default [traceability.configs.recommended];
-```
-
-## 3. New and Updated Rules
-
-- `valid-story-reference` now enforces `.story.md` extensions strictly.
-- `valid-req-reference` rejects path traversal (`../`) and absolute paths (`/etc/passwd`).
-- `valid-annotation-format` enforces correct JSDoc traceability annotation syntax (`@story` and `@req` tags).
-
-Review and update your existing annotations accordingly:
-
-```diff
-- /** @story docs/stories/001.0-DEV-PLUGIN-SETUP.md */
-+ /** @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md */
-```
-
-## 4. CLI Integration Script
-
-Version 1.x includes a new `cli-integration.js` script at the project root to run end-to-end CLI integration tests:
-
-```bash
-node ./cli-integration.js
-```
-
-## 5. Test and Validate
-
-Run your test suite and the new CLI integration script to confirm everything passes:
-
-```bash
-npm test
-npm run lint -- --max-warnings=0
-npm run format:check
-node ./cli-integration.js
-```
-
-## 6. Update Documentation
-
-If you have custom documentation or examples that reference old rule names or file paths, update them to match the new conventions introduced in v1.x.
-
----
-
-If you encounter any issues during migration, please file an issue at https://github.com/voder-ai/eslint-plugin-traceability/issues.