eslint-plugin-traceability 1.0.0

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

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

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

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

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

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