eslint-plugin-traceability 1.1.0 → 1.1.2

package/src/rules/valid-annotation-format.ts

@@ -1,62 +0,0 @@
-/**
- * Rule to validate @story and @req annotation format and syntax
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
- * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
- * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
- * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
- */
-export default {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "Validate format and syntax of @story and @req annotations",
-      recommended: "error",
-    },
-    messages: {
-      invalidStoryFormat: "Invalid @story annotation format",
-      invalidReqFormat: "Invalid @req annotation format",
-    },
-    schema: [],
-  },
-  create(context: any) {
-    const sourceCode = context.getSourceCode();
-    return {
-      Program() {
-        const comments = sourceCode.getAllComments() || [];
-        comments.forEach((comment: any) => {
-          const lines = comment.value
-            .split(/\r?\n/)
-            .map((l: string) => l.replace(/^[^@]*/, "").trim());
-          lines.forEach((line: string) => {
-            if (line.startsWith("@story")) {
-              const parts = line.split(/\s+/);
-              const storyPath = parts[1];
-              if (
-                !storyPath ||
-                !/^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/.test(
-                  storyPath,
-                )
-              ) {
-                context.report({
-                  node: comment as any,
-                  messageId: "invalidStoryFormat",
-                });
-              }
-            }
-            if (line.startsWith("@req")) {
-              const parts = line.split(/\s+/);
-              const reqId = parts[1];
-              if (!reqId || !/^REQ-[A-Z0-9-]+$/.test(reqId)) {
-                context.report({
-                  node: comment as any,
-                  messageId: "invalidReqFormat",
-                });
-              }
-            }
-          });
-        });
-      },
-    };
-  },
-} as any;

package/src/rules/valid-req-reference.ts

@@ -1,114 +0,0 @@
-/* eslint-env node */
-/**
- * Rule to validate @req annotation references refer to existing requirements in story files
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse story files to extract requirement identifiers
- * @req REQ-DEEP-MATCH - Validate @req references against story file content
- * @req REQ-DEEP-CACHE - Cache parsed story content for performance
- * @req REQ-DEEP-PATH - Protect against path traversal in story paths
- */
-import fs from "fs";
-import path from "path";
-import type { Rule } from "eslint";
-
-export default {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Validate that @req annotations reference existing requirements in referenced story files",
-      recommended: "error",
-    },
-    messages: {
-      reqMissing: "Requirement '{{reqId}}' not found in '{{storyPath}}'",
-      invalidPath: "Invalid story path '{{storyPath}}'",
-    },
-    schema: [],
-  },
-  create(context) {
-    const sourceCode = context.getSourceCode();
-    const cwd = process.cwd();
-
-    // Cache for resolved story file paths to parsed set of requirement IDs
-    const reqCache = new Map<string, Set<string>>();
-
-    let rawStoryPath: string | null = null;
-
-    return {
-      Program() {
-        const comments = sourceCode.getAllComments() || [];
-        comments.forEach((comment) => {
-          const rawLines = comment.value.split(/\r?\n/);
-          const lines = rawLines.map((rawLine) =>
-            rawLine.trim().replace(/^\*+\s*/, ""),
-          );
-          lines.forEach((line) => {
-            if (line.startsWith("@story")) {
-              const parts = line.split(/\s+/);
-              rawStoryPath = parts[1] || null;
-            }
-            if (line.startsWith("@req")) {
-              const parts = line.split(/\s+/);
-              const reqId = parts[1];
-              if (!reqId || !rawStoryPath) {
-                return;
-              }
-
-              // Protect against path traversal and absolute paths
-              if (
-                rawStoryPath.includes("..") ||
-                path.isAbsolute(rawStoryPath)
-              ) {
-                context.report({
-                  node: comment as any,
-                  messageId: "invalidPath",
-                  data: { storyPath: rawStoryPath },
-                });
-                return;
-              }
-
-              const resolvedStoryPath = path.resolve(cwd, rawStoryPath);
-              if (
-                !resolvedStoryPath.startsWith(cwd + path.sep) &&
-                resolvedStoryPath !== cwd
-              ) {
-                context.report({
-                  node: comment as any,
-                  messageId: "invalidPath",
-                  data: { storyPath: rawStoryPath },
-                });
-                return;
-              }
-
-              // Load and parse story file if not cached
-              if (!reqCache.has(resolvedStoryPath)) {
-                try {
-                  const content = fs.readFileSync(resolvedStoryPath, "utf8");
-                  const found = new Set<string>();
-                  const regex = /REQ-[A-Z0-9-]+/g;
-                  let match;
-                  while ((match = regex.exec(content)) !== null) {
-                    found.add(match[0]);
-                  }
-                  reqCache.set(resolvedStoryPath, found);
-                } catch {
-                  // Unable to read file, treat as no requirements
-                  reqCache.set(resolvedStoryPath, new Set());
-                }
-              }
-
-              const reqSet = reqCache.get(resolvedStoryPath)!;
-              if (!reqSet.has(reqId)) {
-                context.report({
-                  node: comment as any,
-                  messageId: "reqMissing",
-                  data: { reqId, storyPath: rawStoryPath },
-                });
-              }
-            }
-          });
-        });
-      },
-    };
-  },
-} as Rule.RuleModule;

package/src/rules/valid-story-reference.ts

@@ -1,213 +0,0 @@
-/* eslint-env node */
-/**
- * Rule to validate @story annotation references refer to existing story files
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
- * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
- * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
- */
-import fs from "fs";
-import path from "path";
-import type { Rule } from "eslint";
-
-const defaultStoryDirs = ["docs/stories", "stories"];
-const fileExistCache = new Map<string, boolean>();
-
-/**
- * Build possible file paths for a given storyPath.
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
- */
-function buildCandidates(
-  storyPath: string,
-  cwd: string,
-  storyDirs: string[],
-): string[] {
-  const candidates: string[] = [];
-  if (storyPath.startsWith("./") || storyPath.startsWith("../")) {
-    candidates.push(path.resolve(cwd, storyPath));
-  } else {
-    candidates.push(path.resolve(cwd, storyPath));
-    for (const dir of storyDirs) {
-      candidates.push(path.resolve(cwd, dir, path.basename(storyPath)));
-    }
-  }
-  return candidates;
-}
-
-/**
- * Check if any of the candidate files exist.
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
- */
-function existsAny(paths: string[]): boolean {
-  for (const candidate of paths) {
-    let ok = fileExistCache.get(candidate);
-    if (ok === undefined) {
-      ok = fs.existsSync(candidate) && fs.statSync(candidate).isFile();
-      fileExistCache.set(candidate, ok);
-    }
-    if (ok) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Validate a single @story annotation line.
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
- * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
- * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
- */
-function validateStoryPath(
-  line: string,
-  commentNode: any,
-  context: any,
-  cwd: string,
-  storyDirs: string[],
-  allowAbsolute: boolean,
-  requireExt: boolean,
-): void {
-  const parts = line.split(/\s+/);
-  const storyPath = parts[1];
-  if (!storyPath) {
-    return;
-  }
-  // Absolute path check
-  if (path.isAbsolute(storyPath)) {
-    if (!allowAbsolute) {
-      context.report({
-        node: commentNode,
-        messageId: "invalidPath",
-        data: { path: storyPath },
-      });
-    }
-    return;
-  }
-  // Path traversal prevention
-  if (storyPath.includes("..")) {
-    const normalized = path.normalize(storyPath);
-    const full = path.resolve(cwd, normalized);
-    if (!full.startsWith(cwd + path.sep)) {
-      context.report({
-        node: commentNode,
-        messageId: "invalidPath",
-        data: { path: storyPath },
-      });
-      return;
-    }
-  }
-  // Extension check
-  if (requireExt && !storyPath.endsWith(".story.md")) {
-    context.report({
-      node: commentNode,
-      messageId: "invalidExtension",
-      data: { path: storyPath },
-    });
-    return;
-  }
-  // Build candidate paths and check existence
-  const candidates = buildCandidates(storyPath, cwd, storyDirs);
-  if (!existsAny(candidates)) {
-    context.report({
-      node: commentNode,
-      messageId: "fileMissing",
-      data: { path: storyPath },
-    });
-  }
-}
-
-/**
- * Handle a single comment node by processing its lines.
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
- */
-function handleComment(
-  commentNode: any,
-  context: any,
-  sourceCode: any,
-  cwd: string,
-  storyDirs: string[],
-  allowAbsolute: boolean,
-  requireExt: boolean,
-): void {
-  const lines = commentNode.value
-    .split(/\r?\n/)
-    .map((l: string) => l.replace(/^[^@]*/, "").trim());
-  for (const line of lines) {
-    if (line.startsWith("@story")) {
-      validateStoryPath(
-        line,
-        commentNode,
-        context,
-        cwd,
-        storyDirs,
-        allowAbsolute,
-        requireExt,
-      );
-    }
-  }
-}
-
-export default {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Validate that @story annotations reference existing .story.md files",
-      recommended: "error",
-    },
-    messages: {
-      fileMissing: "Story file '{{path}}' not found",
-      invalidExtension:
-        "Invalid story file extension for '{{path}}', expected '.story.md'",
-      invalidPath: "Invalid story path '{{path}}'",
-    },
-    schema: [
-      {
-        type: "object",
-        properties: {
-          storyDirectories: {
-            type: "array",
-            items: { type: "string" },
-          },
-          allowAbsolutePaths: { type: "boolean" },
-          requireStoryExtension: { type: "boolean" },
-        },
-        additionalProperties: false,
-      },
-    ],
-  },
-  create(context) {
-    const sourceCode = context.getSourceCode();
-    const cwd = process.cwd();
-    const opts = context.options[0] as
-      | {
-          storyDirectories?: string[];
-          allowAbsolutePaths?: boolean;
-          requireStoryExtension?: boolean;
-        }
-      | undefined;
-    const storyDirs = opts?.storyDirectories || defaultStoryDirs;
-    const allowAbsolute = opts?.allowAbsolutePaths || false;
-    const requireExt = opts?.requireStoryExtension !== false;
-    return {
-      Program() {
-        const comments = sourceCode.getAllComments() || [];
-        for (const comment of comments) {
-          handleComment(
-            comment,
-            context,
-            sourceCode,
-            cwd,
-            storyDirs,
-            allowAbsolute,
-            requireExt,
-          );
-        }
-      },
-    };
-  },
-} as Rule.RuleModule;

package/tests/fixtures/story_bullet.md

@@ -1,6 +0,0 @@
-# Story Bullet Format
-
-## Requirements
-
-- REQ-BULLET-LIST - a requirement in bullet list format
-- REQ-ANOTHER - another requirement

package/tests/maintenance/batch.test.ts

@@ -1,55 +0,0 @@
-/**
- * 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
- */
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import {
-  batchUpdateAnnotations,
-  verifyAnnotations,
-} from "../../src/maintenance/batch";
-
-describe("batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  let tmpDir: string;
-
-  beforeAll(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "batch-test-"));
-  });
-
-  afterAll(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("[REQ-MAINT-BATCH] should return 0 when no mappings applied", () => {
-    const count = batchUpdateAnnotations(tmpDir, []);
-    expect(count).toBe(0);
-  });
-});
-
-describe("verifyAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  let tmpDir: string;
-
-  beforeAll(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "verify-test-"));
-    const tsContent = `
-/**
- * Tests for: my-story.story.md
- * @story my-story.story.md
- */
-`;
-    fs.writeFileSync(path.join(tmpDir, "test.ts"), tsContent);
-    fs.writeFileSync(path.join(tmpDir, "my-story.story.md"), "# Dummy Story");
-  });
-
-  afterAll(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("[REQ-MAINT-VERIFY] should return true when annotations are valid", () => {
-    const valid = verifyAnnotations(tmpDir);
-    expect(valid).toBe(true);
-  });
-});

package/tests/maintenance/detect-isolated.test.ts

@@ -1,65 +0,0 @@
-/**
- * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Detect stale annotation references
- */
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { detectStaleAnnotations } from "../../src/maintenance/detect";
-
-describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  it("[REQ-MAINT-DETECT] returns empty array when directory does not exist", () => {
-    const result = detectStaleAnnotations("non-existent-dir");
-    expect(result).toEqual([]);
-  });
-
-  it("[REQ-MAINT-DETECT] detects stale annotations in nested directories", () => {
-    // Arrange
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-nested-"));
-    const nestedDir = path.join(tmpDir, "nested");
-    fs.mkdirSync(nestedDir);
-    const filePath1 = path.join(tmpDir, "file1.ts");
-    const filePath2 = path.join(nestedDir, "file2.ts");
-    const content1 = `
-/**
- * @story stale1.story.md
- */
-`;
-    fs.writeFileSync(filePath1, content1, "utf8");
-    const content2 = `
-/**
- * @story stale2.story.md
- */
-`;
-    fs.writeFileSync(filePath2, content2, "utf8");
-
-    // Act
-    const result = detectStaleAnnotations(tmpDir);
-
-    // Assert
-    expect(result).toHaveLength(2);
-    expect(result).toContain("stale1.story.md");
-    expect(result).toContain("stale2.story.md");
-  });
-
-  it("[REQ-MAINT-DETECT] throws error on permission denied", () => {
-    const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
-    const dir = path.join(tmpDir2, "subdir");
-    fs.mkdirSync(dir);
-    const filePath = path.join(dir, "file.ts");
-    const content = `
-/**
- * @story none.story.md
- */
-`;
-    fs.writeFileSync(filePath, content, "utf8");
-    // Remove read permission
-    fs.chmodSync(dir, 0o000);
-    expect(() => detectStaleAnnotations(tmpDir2)).toThrow();
-    // Restore permissions
-    fs.chmodSync(dir, 0o700);
-    // Cleanup temporary directory
-    fs.rmSync(tmpDir2, { recursive: true, force: true });
-  });
-});

package/tests/maintenance/detect.test.ts

@@ -1,19 +0,0 @@
-/**
- * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Detect stale annotation references
- */
-import fs from "fs";
-import path from "path";
-import os from "os";
-import { detectStaleAnnotations } from "../../src/maintenance/detect";
-
-describe("detectStaleAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  it("[REQ-MAINT-DETECT] should return empty array when no stale annotations", () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "detect-test-"));
-    // No annotation files are created in tmpDir to simulate no stale annotations
-    const result = detectStaleAnnotations(tmpDir);
-    expect(result).toEqual([]);
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-});

package/tests/maintenance/report.test.ts

@@ -1,37 +0,0 @@
-/**
- * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-REPORT - Generate maintenance report
- * @req REQ-MAINT-SAFE - Ensure operations are safe and reversible
- */
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { generateMaintenanceReport } from "../../src/maintenance/report";
-
-describe("generateMaintenanceReport (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  let tmpDir: string;
-
-  beforeAll(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "report-test-"));
-  });
-
-  afterAll(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("[REQ-MAINT-REPORT] should return empty string when no operations", () => {
-    const report = generateMaintenanceReport(tmpDir);
-    expect(report).toBe("");
-  });
-
-  it("[REQ-MAINT-REPORT] should report stale story annotation", () => {
-    const filePath = path.join(tmpDir, "stub.md");
-    const content = `/**
- * @story non-existent.md
- */`;
-    fs.writeFileSync(filePath, content);
-    const report = generateMaintenanceReport(tmpDir);
-    expect(report).toContain("non-existent.md");
-  });
-});

package/tests/maintenance/update-isolated.test.ts

@@ -1,39 +0,0 @@
-/**
- * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-UPDATE - Update annotation references
- */
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { updateAnnotationReferences } from "../../src/maintenance/update";
-
-describe("updateAnnotationReferences isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  it("[REQ-MAINT-UPDATE] updates @story annotations in files", () => {
-    // Create a temporary directory for testing
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-"));
-    const filePath = path.join(tmpDir, "file.ts");
-    const originalContent = `
-/**
- * @story old.path.md
- */
-function foo() {}
-`;
-    fs.writeFileSync(filePath, originalContent, "utf8");
-
-    // Run the function under test
-    const count = updateAnnotationReferences(
-      tmpDir,
-      "old.path.md",
-      "new.path.md",
-    );
-    expect(count).toBe(1);
-
-    // Verify the file content was updated
-    const updatedContent = fs.readFileSync(filePath, "utf8");
-    expect(updatedContent).toContain("@story new.path.md");
-
-    // Cleanup temporary directory
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-});

package/tests/maintenance/update.test.ts

@@ -1,21 +0,0 @@
-/**
- * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-UPDATE - Update annotation references
- */
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { updateAnnotationReferences } from "../../src/maintenance/update";
-
-describe("updateAnnotationReferences (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-  it("[REQ-MAINT-UPDATE] should return 0 when no updates made", () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "update-test-"));
-    try {
-      const count = updateAnnotationReferences(tmpDir, "old.md", "new.md");
-      expect(count).toBe(0);
-    } finally {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-});

package/tests/plugin-default-export-and-configs.test.ts

@@ -1,50 +0,0 @@
-/**
- * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Validate plugin default export and configs in src/index.ts
- */
-import plugin, { rules, configs } from "../src/index";
-
-describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", () => {
-  it("[REQ-PLUGIN-STRUCTURE] default export includes rules and configs", () => {
-    expect(plugin.rules).toBe(rules);
-    expect(plugin.configs).toBe(configs);
-  });
-
-  it("[REQ-PLUGIN-STRUCTURE] rules object has correct rule names", () => {
-    // Arrange: expected rule names in insertion order
-    const expected = [
-      "require-story-annotation",
-      "require-req-annotation",
-      "require-branch-annotation",
-      "valid-annotation-format",
-      "valid-story-reference",
-      "valid-req-reference",
-    ];
-    // Act: get actual rule names from plugin
-    const actual = Object.keys(rules);
-    // Assert: actual matches expected
-    expect(actual).toEqual(expected);
-  });
-
-  it("[REQ-RULE-REGISTRY] configs.recommended contains correct rule configuration", () => {
-    const recommendedRules = configs.recommended[0].rules;
-    expect(recommendedRules).toHaveProperty(
-      "traceability/require-story-annotation",
-      "error",
-    );
-    expect(recommendedRules).toHaveProperty(
-      "traceability/require-req-annotation",
-      "error",
-    );
-    expect(recommendedRules).toHaveProperty(
-      "traceability/require-branch-annotation",
-      "error",
-    );
-  });
-
-  it("[REQ-CONFIG-SYSTEM] configs.strict contains same rules as recommended", () => {
-    const strictRules = configs.strict[0].rules;
-    expect(strictRules).toEqual(configs.recommended[0].rules);
-  });
-});