eslint-plugin-traceability 1.1.1 → 1.1.3

package/docs/eslint-plugin-development-guide.md

@@ -1,483 +0,0 @@
-# ESLint Plugin Development Guidance
-
-This document provides comprehensive guidance for developing ESLint plugins, specifically tailored for the eslint-plugin-traceability project. It's based on the official [ESLint plugin documentation](https://eslint.org/docs/latest/extend/plugins) and includes project-specific considerations.
-
-## Plugin Structure Overview
-
-An ESLint plugin is a JavaScript object that exposes specific properties to ESLint:
-
-- `meta` - information about the plugin
-- `configs` - an object containing named configurations
-- `rules` - an object containing custom rule definitions
-- `processors` - an object containing named processors
-
-## Basic Plugin Template
-
-```typescript
-// src/index.ts
-const plugin = {
-  meta: {
-    name: "eslint-plugin-traceability",
-    version: "1.0.0",
-    namespace: "traceability",
-  },
-  configs: {},
-  rules: {},
-  processors: {},
-};
-
-// for ESM source (compiled to CommonJS)
-export default plugin;
-```
-
-## Meta Data Requirements
-
-### Essential Meta Properties
-
-Every plugin should include meta information for debugging and caching:
-
-```typescript
-const plugin = {
-  meta: {
-    name: "eslint-plugin-traceability", // npm package name
-    version: "1.0.0", // npm package version
-    namespace: "traceability", // prefix for rules/configs
-  },
-  // ... other properties
-};
-```
-
-### Reading from package.json
-
-For maintainability, read name and version from package.json:
-
-```typescript
-import fs from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const pkg = JSON.parse(
-  fs.readFileSync(join(__dirname, "../package.json"), "utf8"),
-);
-
-const plugin = {
-  meta: {
-    name: pkg.name,
-    version: pkg.version,
-    namespace: "traceability",
-  },
-  // ... other properties
-};
-```
-
-## Rule Development
-
-### Rule Structure
-
-Rules are the core functionality of an ESLint plugin:
-
-```typescript
-const plugin = {
-  meta: {
-    name: "eslint-plugin-traceability",
-    version: "1.0.0",
-    namespace: "traceability",
-  },
-  rules: {
-    "require-story-annotation": {
-      meta: {
-        type: "problem",
-        docs: {
-          description: "require @story annotations on functions",
-          category: "Traceability",
-          recommended: true,
-        },
-        schema: [
-          {
-            type: "object",
-            properties: {
-              // rule options
-            },
-            additionalProperties: false,
-          },
-        ],
-        messages: {
-          missingStory: "Function '{{name}}' is missing @story annotation",
-          invalidStoryFormat: "@story annotation format is invalid: {{format}}",
-        },
-      },
-      create(context) {
-        return {
-          FunctionDeclaration(node) {
-            // rule implementation
-          },
-        };
-      },
-    },
-  },
-};
-```
-
-### Rule Implementation Guidelines
-
-1. **Use TypeScript for type safety**: Leverage @typescript-eslint/utils for AST manipulation
-2. **Clear error messages**: Provide helpful, actionable error messages
-3. **Configurable options**: Allow users to customize rule behavior
-4. **Performance**: Avoid expensive operations in visitors
-5. **Testing**: Use ESLint's RuleTester for comprehensive testing
-
-### AST Node Handling
-
-When working with AST nodes, use TypeScript for safety:
-
-```typescript
-import { TSESTree } from "@typescript-eslint/utils";
-
-function checkFunctionAnnotation(node: TSESTree.FunctionDeclaration) {
-  // Type-safe AST manipulation
-  if (node.id?.name) {
-    // Check for @story annotation in comments
-  }
-}
-```
-
-## Configuration Presets
-
-### Recommended Configuration
-
-Provide a recommended configuration for common use cases:
-
-```typescript
-const plugin = {
-  // ... meta and rules
-  configs: {},
-};
-
-// Assign configs after plugin definition to reference plugin
-Object.assign(plugin.configs, {
-  recommended: [
-    {
-      plugins: {
-        traceability: plugin,
-      },
-      rules: {
-        "traceability/require-story-annotation": "error",
-        "traceability/require-req-annotation": "error",
-        "traceability/valid-story-reference": "error",
-        "traceability/valid-req-reference": "error",
-      },
-    },
-  ],
-  strict: [
-    {
-      plugins: {
-        traceability: plugin,
-      },
-      rules: {
-        "traceability/require-story-annotation": "error",
-        "traceability/require-req-annotation": "error",
-        "traceability/valid-story-reference": "error",
-        "traceability/valid-req-reference": "error",
-        "traceability/require-branch-annotation": "error",
-      },
-    },
-  ],
-});
-```
-
-### Configuration Usage
-
-Users can extend configurations in their eslint.config.js:
-
-```javascript
-// eslint.config.js
-import { defineConfig } from "eslint/config";
-import traceability from "eslint-plugin-traceability";
-
-export default defineConfig([
-  {
-    files: ["src/**/*.{js,ts}"],
-    plugins: {
-      traceability,
-    },
-    extends: ["traceability/recommended"],
-  },
-]);
-```
-
-## Testing Strategy
-
-### Using ESLint's RuleTester
-
-```typescript
-// tests/rules/require-story-annotation.test.ts
-import { RuleTester } from "eslint";
-import rule from "../../src/rules/require-story-annotation";
-
-const ruleTester = new RuleTester({
-  parser: require.resolve("@typescript-eslint/parser"),
-  parserOptions: {
-    ecmaVersion: 2020,
-    sourceType: "module",
-  },
-});
-
-ruleTester.run("require-story-annotation", rule, {
-  valid: [
-    {
-      code: `
-        /**
-         * @story docs/stories/001.0-DEV-EXAMPLE.story.md
-         * @req REQ-EXAMPLE
-         */
-        function validFunction() {}
-      `,
-    },
-  ],
-  invalid: [
-    {
-      code: `function invalidFunction() {}`,
-      errors: [
-        {
-          messageId: "missingStory",
-          data: { name: "invalidFunction" },
-        },
-      ],
-    },
-  ],
-});
-```
-
-### Test Organization
-
-- **Unit tests**: Test individual rules in isolation
-- **Integration tests**: Test plugin loading and configuration
-- **File system tests**: Test file reference validation (use temporary directories)
-
-## Project-Specific Considerations
-
-### File System Integration
-
-For validating @story references to actual files:
-
-```typescript
-import fs from "fs/promises";
-import path from "path";
-
-async function validateStoryFile(
-  storyPath: string,
-  context: any,
-): Promise<boolean> {
-  try {
-    const fullPath = path.resolve(context.getCwd(), storyPath);
-
-    // Check file exists
-    await fs.access(fullPath);
-
-    // Check file extension
-    if (!fullPath.endsWith(".story.md")) {
-      return false;
-    }
-
-    return true;
-  } catch {
-    return false;
-  }
-}
-```
-
-### Requirement Reference Validation
-
-For validating @req references within story files:
-
-```typescript
-async function validateRequirement(
-  storyPath: string,
-  reqId: string,
-): Promise<boolean> {
-  try {
-    const content = await fs.readFile(storyPath, "utf8");
-
-    // Look for requirement ID in story content
-    const reqPattern = new RegExp(`\\*\\*${reqId}\\*\\*:`, "g");
-    return reqPattern.test(content);
-  } catch {
-    return false;
-  }
-}
-```
-
-### Configuration Options
-
-Allow users to customize behavior:
-
-```typescript
-interface RuleOptions {
-  storyFilePattern?: string; // Default: "**/*.story.md"
-  requirementPattern?: string; // Default: "REQ-*"
-  excludePatterns?: string[]; // Files to exclude
-  includePrivateFunctions?: boolean; // Default: false
-}
-```
-
-## Build and Distribution
-
-### TypeScript Configuration
-
-Configure TypeScript to output CommonJS for ESLint compatibility:
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "moduleResolution": "node",
-    "declaration": true,
-    "outDir": "./lib",
-    "strict": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib", "tests"]
-}
-```
-
-### Package.json Configuration
-
-Essential package.json settings for ESLint plugins:
-
-```json
-{
-  "name": "eslint-plugin-traceability",
-  "version": "1.0.0",
-  "description": "ESLint plugin for enforcing code traceability annotations",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "keywords": ["eslint", "eslintplugin", "eslint-plugin", "traceability"],
-  "peerDependencies": {
-    "eslint": ">=9.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
-```
-
-## Development Workflow
-
-### Local Testing
-
-1. **Link locally**: Use `npm link` for local development
-2. **Test project**: Create a test project to verify plugin behavior
-3. **Rule tester**: Use ESLint's RuleTester for individual rule testing
-4. **Integration testing**: Test complete plugin configuration
-
-### Quality Checks
-
-Recommended linting for the plugin itself:
-
-```javascript
-// eslint.config.js (for the plugin project)
-import js from "@eslint/js";
-import typescript from "@typescript-eslint/eslint-plugin";
-import eslintPlugin from "eslint-plugin-eslint-plugin";
-
-export default [
-  js.configs.recommended,
-  {
-    plugins: {
-      "@typescript-eslint": typescript,
-      "eslint-plugin": eslintPlugin,
-    },
-    rules: {
-      // Plugin-specific linting rules
-    },
-  },
-];
-```
-
-## Performance Considerations
-
-### Efficient AST Traversal
-
-- **Minimal visitors**: Only register for needed node types
-- **Early returns**: Exit early when conditions aren't met
-- **Caching**: Cache expensive operations (file reads, regex compilation)
-- **Async handling**: Use proper async patterns for file operations
-
-### Memory Management
-
-- **Avoid global state**: Keep rule instances isolated
-- **Clean up resources**: Properly handle file handles and timers
-- **Limit recursion**: Avoid deep recursive operations
-
-## Documentation Requirements
-
-### Rule Documentation
-
-Each rule should have comprehensive documentation:
-
-```typescript
-const rule = {
-  meta: {
-    docs: {
-      description: "require @story annotations on functions",
-      category: "Traceability",
-      recommended: true,
-      url: "https://github.com/voder-ai/eslint-plugin-traceability#require-story-annotation",
-    },
-    // ... other meta properties
-  },
-  // ... rule implementation
-};
-```
-
-### README Structure
-
-Include in the plugin README:
-
-1. **Installation instructions**
-2. **Configuration examples**
-3. **Rule documentation**
-4. **Usage examples**
-5. **Troubleshooting guide**
-
-## Security Considerations
-
-### File System Access
-
-- **Validate paths**: Prevent directory traversal attacks
-- **Sanitize input**: Validate user-provided file patterns
-- **Limit scope**: Restrict file access to project directory
-
-### Input Validation
-
-- **Schema validation**: Use JSON Schema for rule options
-- **Type checking**: Leverage TypeScript for compile-time safety
-- **Runtime checks**: Validate configuration at runtime
-
-## Maintenance Guidelines
-
-### Version Management
-
-- **Semantic versioning**: Follow semver for releases
-- **Breaking changes**: Document breaking changes clearly
-- **Migration guides**: Provide upgrade instructions
-
-### Community Support
-
-- **Issue templates**: Provide clear bug report templates
-- **Contributing guide**: Document contribution process
-- **Code of conduct**: Establish community guidelines
-
----
-
-## Related Resources
-
-- [ESLint Plugin Development Guide](https://eslint.org/docs/latest/extend/plugins)
-- [ESLint Custom Rules](https://eslint.org/docs/latest/extend/custom-rules)
-- [@typescript-eslint/utils](https://typescript-eslint.io/packages/utils/)
-- [ESLint RuleTester](https://eslint.org/docs/latest/integrate/nodejs-api#ruletester)

package/docs/jest-testing-guide.md

@@ -1,100 +0,0 @@
-# Jest Testing Guide
-
-This guide covers testing practices and configuration for the eslint-plugin-traceability project.
-
-## Traceability in Test Output
-
-### Viewing Story and Requirement References
-
-By default, Jest's standard output only shows file-level test results without displaying individual test descriptions or traceability annotations. To see the full traceability information including story references and requirement IDs, you must use the `--verbose` option.
-
-**Standard output (limited visibility):**
-
-```bash
-npm test
-```
-
-Shows only:
-
-```
- PASS  tests/maintenance/batch.test.ts
- PASS  tests/rules/require-branch-annotation.test.ts
-```
-
-**Verbose output (full traceability):**
-
-```bash
-npm test -- --verbose
-```
-
-Shows detailed test descriptions with traceability annotations:
-
-```
- PASS  tests/maintenance/batch.test.ts
-  batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)
-    ✓ [REQ-MAINT-BATCH] should return 0 when no mappings applied (6 ms)
-  verifyAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)
-    ✓ [REQ-MAINT-VERIFY] should return true when annotations are valid
-
- PASS  tests/rules/require-branch-annotation.test.ts
-  Require Branch Annotation Rule (Story 004.0-DEV-BRANCH-ANNOTATIONS)
-    require-branch-annotation
-      valid
-        ✓ [REQ-BRANCH-DETECTION] valid if-statement with annotations (4 ms)
-```
-
-### Test Structure Requirements
-
-All tests in this project follow a specific structure to support traceability:
-
-1. **File-level annotations** at the top of each test file:
-
-   ```typescript
-   /**
-    * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    * @req REQ-MAINT-BATCH - Perform batch updates
-    * @req REQ-MAINT-VERIFY - Verify annotation references
-    */
-   ```
-
-2. **Describe blocks** that reference the story:
-
-   ```typescript
-   describe('batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)', () => {
-   ```
-
-3. **Test cases** that reference specific requirements:
-   ```typescript
-   it('[REQ-MAINT-BATCH] should return 0 when no mappings applied', () => {
-   ```
-
-### Running Tests for Traceability Review
-
-When reviewing test coverage for specific stories or requirements:
-
-- **For development/debugging**: Use `npm test -- --verbose` to see all traceability information
-- **For CI/CD pipelines**: Standard `npm test` provides sufficient pass/fail information
-- **For coverage analysis**: Both modes provide the same coverage statistics
-
-### Best Practices
-
-1. **Always include story references** in describe blocks to make them visible in verbose output
-2. **Prefix test descriptions with requirement IDs** in square brackets (e.g., `[REQ-MAINT-BATCH]`)
-3. **Use meaningful test descriptions** that clearly indicate what requirement is being tested
-4. **Run with --verbose during development** to verify traceability annotations are properly displayed
-
-## Configuration
-
-The project's Jest configuration is defined in `jest.config.js` and includes:
-
-- Coverage reporting
-- TypeScript support via ts-jest
-- Test file patterns
-- CI-friendly options (--ci --bail --coverage)
-
-## Related Documentation
-
-- [Story Files](stories/) - User story definitions
-- [ESLint Plugin Development Guide](eslint-plugin-development-guide.md) - General development practices
-- [Decision Records](decisions/) - Architectural decisions including Jest adoption

package/docs/rules/require-branch-annotation.md

@@ -1,34 +0,0 @@
-# require-branch-annotation
-
-Ensures that significant code branches (if/else, switch cases, loops, try/catch) have `@story` and `@req` annotations for traceability.
-
-@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-@req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
-
-## Rule Details
-
-This rule checks for JSDoc or inline comments immediately preceding significant code branches and ensures both `@story` and `@req` annotations are present.
-
-### Options Schema
-
-This rule does not accept any options (schema is `[]`).
-
-### Examples
-
-#### Correct
-
-```js
-// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-DETECTION
-if (error) {
-  handleError();
-}
-```
-
-#### Incorrect
-
-```js
-if (error) {
-  handleError();
-}
-```

package/docs/rules/require-req-annotation.md

@@ -1,39 +0,0 @@
-# require-req-annotation
-
-Enforces the presence of `@req` annotations on function declarations to ensure each function maps to a specific requirement ID.
-
-@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-@req REQ-ANNOTATION-REQUIRED - Require `@req` annotation on functions
-
-## Rule Details
-
-This rule validates that every function declaration has a JSDoc comment containing an `@req` annotation.
-
-### Options Schema
-
-This rule does not accept any options (schema is `[]`).
-
-### Examples
-
-#### Correct
-
-```js
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- */
-function initAuth() {
-  // authentication logic
-}
-```
-
-#### Incorrect
-
-```js
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- */
-function initAuth() {
-  // authentication logic
-}
-```

package/docs/rules/require-story-annotation.md

@@ -1,36 +0,0 @@
-# require-story-annotation
-
-Enforces the presence of `@story` annotations on function declarations to ensure traceability from code to user stories.
-
-@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-@req REQ-ANNOTATION-REQUIRED - Require `@story` annotation on functions
-
-## Rule Details
-
-This rule validates that every function declaration has a JSDoc comment containing an `@story` annotation pointing to the relevant story file.
-
-### Options Schema
-
-This rule does not accept any options (schema is `[]`).
-
-### Examples
-
-#### Correct
-
-```js
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- */
-function initAuth() {
-  // authentication logic
-}
-```
-
-#### Incorrect
-
-```js
-function initAuth() {
-  // authentication logic
-}
-```