eslint-plugin-traceability 1.0.3 → 1.0.4

package/cli-integration.js

@@ -1,56 +1,18 @@
 #!/usr/bin/env node
-/* eslint-env node */
 /**
- * CLI integration tests for ESLint Traceability Plugin
+ * CLI integration tests script for ESLint Traceability Plugin
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
  */
 const { spawnSync } = require("child_process");
 const path = require("path");
-const configPath = path.resolve(__dirname, "eslint.config.js");
 
-/**
- * Helper to execute ESLint CLI integration tests for the traceability plugin
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Utility for invoking ESLint with flat config in integration tests
- */
-function runEslint(code, rule) {
-  const eslintPkgDir = path.dirname(require.resolve("eslint/package.json"));
-  const eslintCliPath = path.join(eslintPkgDir, "bin", "eslint.js");
-  const args = [
-    "--no-config-lookup",
-    "--config",
-    configPath,
-    "--stdin",
-    "--stdin-filename",
-    "foo.js",
-    "--rule",
-    "no-unused-vars:off",
-    "--rule",
-    "no-constant-condition:off",
-    "--rule",
-    "no-empty:off",
-    "--rule",
-    "traceability/require-story-annotation:off",
-    "--rule",
-    "traceability/require-req-annotation:off",
-    "--rule",
-    "traceability/require-branch-annotation:off",
-    "--rule",
-    "traceability/valid-annotation-format:off",
-    "--rule",
-    "traceability/valid-story-reference:off",
-    "--rule",
-    "traceability/valid-req-reference:off",
-    "--rule",
-    rule,
-  ];
-  return spawnSync(process.execPath, [eslintCliPath, ...args], {
-    encoding: "utf-8",
-    input: code,
-  });
-}
+// Resolve the ESLint CLI binary and configuration path
+const eslintPkgDir = path.dirname(require.resolve("eslint/package.json"));
+const eslintCliPath = path.join(eslintPkgDir, "bin", "eslint.js");
+const configPath = path.resolve(__dirname, "eslint.config.js");
 
+// Define CLI integration test scenarios
 const tests = [
   {
     name: "reports error when @story annotation is missing",
@@ -60,98 +22,82 @@ const tests = [
   },
   {
     name: "does not report error when @story annotation is present",
-    code: `
-/**
+    code: `/**
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  */
-function foo() {}
-`,
+function foo() {}`,
     rule: "traceability/require-story-annotation:error",
     expectedStatus: 0,
   },
-  {
-    name: "reports error when requirement reference is missing",
-    code: `/**\n * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-NON-EXISTENT\n */\nfunction foo() {}`,
-    rule: "traceability/valid-req-reference:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "reports error when requirement reference uses path traversal",
-    code: `/**\n * @story ../docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-PLUGIN-STRUCTURE\n */\nfunction foo() {}`,
-    rule: "traceability/valid-req-reference:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "reports error when requirement reference uses absolute path",
-    code: `/**\n * @story /absolute/docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-PLUGIN-STRUCTURE\n */\nfunction foo() {}`,
-    rule: "traceability/valid-req-reference:error",
-    expectedStatus: 1,
-  },
   {
     name: "reports error when @req annotation is missing",
-    code: `/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- */\nfunction foo() {}`,
+    code: "function bar() {}",
     rule: "traceability/require-req-annotation:error",
     expectedStatus: 1,
   },
   {
-    name: "does not report error when @req annotation is present",
+    name: "reports error when @story annotation uses path traversal and @req annotation uses path traversal",
     code: `/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- */\nfunction foo() {}`,
-    rule: "traceability/require-req-annotation:error",
-    expectedStatus: 0,
-  },
-  {
-    name: "reports error for missing branch annotations",
-    code: `if (true) {}`,
-    rule: "traceability/require-branch-annotation:error",
-    expectedStatus: 1,
-  },
-  {
-    name: "does not report error for branch with annotations",
-    code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n// @req REQ-BRANCH-DETECTION\nif (true) {}`,
-    rule: "traceability/require-branch-annotation:error",
-    expectedStatus: 0,
-  },
-  {
-    name: "reports invalid annotation format",
-    code: `/**\n * @story invalid/path.txt\n * @req INVALID\n */\nfunction foo() {}`,
-    rule: "traceability/valid-annotation-format:error",
+ * @story ../docs/stories/invalid.story.md
+ * @req ../docs/requirements/REQ-INVALID.md
+ */
+function bar() {}`,
+    rule: "traceability/valid-req-reference:error",
     expectedStatus: 1,
   },
   {
-    name: "valid annotation format passes",
-    code: `/**\n * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md\n * @req REQ-FORMAT-SPECIFICATION\n */\nfunction foo() {}`,
-    rule: "traceability/valid-annotation-format:error",
-    expectedStatus: 0,
-  },
-  {
-    name: "reports missing story file reference",
-    code: `/**\n * @story docs/stories/nonexistent.story.md\n */\nfunction foo() {}`,
-    rule: "traceability/valid-story-reference:error",
+    name: "reports error when @story annotation uses absolute path and @req annotation uses absolute path",
+    code: `/**
+ * @story /absolute/path/to/story.story.md
+ * @req /etc/passwd
+ */
+function baz() {}`,
+    rule: "traceability/valid-req-reference:error",
     expectedStatus: 1,
   },
-  {
-    name: "existing story file reference passes",
-    code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction foo() {}`,
-    rule: "traceability/valid-story-reference:error",
-    expectedStatus: 0,
-  },
 ];
 
-let exitCode = 0;
-tests.forEach(({ name, code, rule, expectedStatus }) => {
-  const result = runEslint(code, rule);
-  if (result.status !== expectedStatus) {
+/**
+ * Run ESLint CLI with given code and rule override
+ * @param {string} code Source code to lint via stdin
+ * @param {string} rule ESLint rule override e.g. "traceability/require-story-annotation:error"
+ * @returns {object} Result of spawnSync call
+ */
+function runEslint(code, rule) {
+  const args = [
+    "--no-config-lookup",
+    "--config",
+    configPath,
+    "--stdin",
+    "--stdin-filename",
+    "foo.js",
+    "--rule",
+    "no-unused-vars:off",
+    "--rule",
+    rule,
+  ];
+  return spawnSync(process.execPath, [eslintCliPath, ...args], {
+    encoding: "utf-8",
+    input: code,
+  });
+}
+
+// Execute tests and report results
+let failures = 0;
+tests.forEach((test) => {
+  const result = runEslint(test.code, test.rule);
+  const passed = result.status === test.expectedStatus;
+  if (passed) {
+    console.log(`✓ ${test.name}`);
+  } else {
+    console.error(`✗ ${test.name}`);
     console.error(
-      `Test "${name}" failed. Expected status ${expectedStatus}, got ${result.status}.`,
+      `  Expected exit code ${test.expectedStatus}, got ${result.status}`,
     );
-    console.error("stdout:", result.stdout);
-    exitCode = 1;
+    if (result.stdout) console.error(`  stdout: ${result.stdout}`);
+    if (result.stderr) console.error(`  stderr: ${result.stderr}`);
+    failures++;
   }
 });
 
-process.exit(exitCode);
+process.exit(failures > 0 ? 1 : 0);

package/docs/cli-integration.md

@@ -74,9 +74,11 @@ Current test scenarios:
 
 ## Usage
 
+Note: The script lives at the project root.
+
 ```bash
 # Run CLI integration tests
-node cli-integration.js
+node ./cli-integration.js
 ```
 
 ## Integration into CI

package/docs/decisions/005-github-actions-validation-tooling.accepted.md

@@ -0,0 +1,144 @@
+---
+status: "accepted"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    GitHub Actions Documentation,
+    Super-Linter Community,
+    actionlint Documentation,
+  ]
+informed: [Project Contributors, CI/CD Pipeline Maintainers]
+---
+
+# GitHub Actions Validation Tooling Selection
+
+## Context and Problem Statement
+
+The project uses GitHub Actions for CI/CD workflows defined in `.github/workflows/`. To prevent broken GitHub Actions files from being pushed to the repository, we need to implement pre-commit validation for GitHub Actions YAML files. This validation should catch syntax errors, invalid action references, and misconfigured job dependencies before they are committed, as broken workflow files could prevent CI/CD from running at all.
+
+## Decision Drivers
+
+- Need for pre-commit validation to prevent broken GitHub Actions files from being pushed
+- Performance requirements for fast local development workflows
+- Prevention of workflow files that would break CI/CD execution
+- Integration with existing development tools and pre-commit hooks
+- Maintainability and configuration simplicity
+- Resource efficiency for local development environments
+
+## Considered Options
+
+- actionlint for pre-commit hooks only
+- actionlint for both pre-commit and CI/CD
+- Super-Linter for pre-commit hooks
+- GitHub's built-in validation only
+
+## Decision Outcome
+
+Chosen option: "actionlint for pre-commit hooks only", because it prevents broken GitHub Actions files from being pushed while maintaining fast local development workflow. Once files reach CI/CD, if the workflow runs successfully, the files are valid by definition.
+
+### Consequences
+
+- Good, because actionlint provides fast pre-commit validation without container overhead
+- Good, because prevents broken GitHub Actions files from being pushed
+- Good, because specifically designed for GitHub Actions validation
+- Good, because simple configuration and maintenance
+- Good, because no Docker dependencies for local development
+- Good, because excellent performance for pre-commit hooks
+- Good, because integrates seamlessly with existing Husky-based pre-commit hooks
+- Neutral, because CI/CD validation is unnecessary if workflows execute successfully
+- Bad, because limited to GitHub Actions validation only
+- Bad, because no security vulnerability detection in pre-commit phase
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- actionlint added to Husky pre-commit hook in `.husky/pre-commit`
+- Pre-commit hook blocks commits with GitHub Actions validation errors
+- actionlint configured to validate files in `.github/workflows/`
+- Documentation updated to explain Husky-based pre-commit validation approach
+
+### Implementation Approach
+
+actionlint will be integrated into existing Husky-based pre-commit hooks by:
+
+- Installing actionlint as a development dependency
+- Adding actionlint validation to `.husky/pre-commit` hook
+- Configuring actionlint to check `.github/workflows/*.yml` files
+- Documenting the validation process for contributors
+
+## Pros and Cons of the Options
+
+### actionlint for pre-commit hooks only
+
+Lightweight, focused pre-commit validation to prevent broken GitHub Actions files.
+
+- Good, because fast execution without container overhead
+- Good, because specifically designed for GitHub Actions validation
+- Good, because no Docker dependencies for local development
+- Good, because simple configuration and maintenance
+- Good, because excellent performance for pre-commit hooks
+- Good, because prevents broken workflow files from being pushed
+- Good, because minimal tooling - only runs where validation is needed
+- Neutral, because focused scope reduces complexity
+- Neutral, because CI/CD validation unnecessary if workflows execute successfully
+- Bad, because limited to GitHub Actions validation only
+- Bad, because no security vulnerability detection in pre-commit phase
+
+### actionlint for both pre-commit and CI/CD
+
+Validation in both development and CI/CD environments.
+
+- Good, because fast execution in all environments
+- Good, because specifically designed for GitHub Actions
+- Good, because consistent validation across environments
+- Neutral, because focused scope reduces complexity
+- Bad, because unnecessary duplication - CI/CD execution validates workflow correctness
+- Bad, because adds CI/CD overhead for validation that's already proven by execution
+- Bad, because limited to GitHub Actions validation only
+
+### Super-Linter for pre-commit hooks
+
+Comprehensive linting solution for pre-commit validation.
+
+- Good, because comprehensive validation including security checks
+- Good, because validates multiple file types beyond GitHub Actions
+- Neutral, because well-maintained and widely adopted
+- Bad, because container overhead makes pre-commit hooks slow
+- Bad, because heavy resource usage for simple syntax checking
+- Bad, because Docker dependency required for local development
+- Bad, because not optimized for frequent pre-commit execution
+- Bad, because overkill for the specific problem of preventing broken workflow files
+
+### GitHub's built-in validation only
+
+Rely solely on GitHub's native workflow validation.
+
+- Good, because no additional tooling or configuration required
+- Good, because automatically available in GitHub interface
+- Good, because validated by the same system that executes workflows
+- Neutral, because basic validation is always performed
+- Bad, because no pre-commit validation for early error detection
+- Bad, because broken files can be pushed, preventing CI/CD execution
+- Bad, because errors only discovered after push to repository
+- Bad, because no local development feedback
+
+## More Information
+
+This decision focuses on solving the specific problem of preventing broken GitHub Actions files from being pushed to the repository. If CI/CD workflows execute successfully, the files are validated by definition - there's no need for redundant validation in the CI/CD pipeline itself.
+
+actionlint configuration should be added to the existing Husky pre-commit hook in `.husky/pre-commit`, targeting `.github/workflows/*.yml` files to catch syntax and configuration errors before commit.
+
+The decision should be re-evaluated if:
+
+- Security vulnerability detection becomes a requirement for pre-commit validation
+- Comprehensive multi-language linting becomes necessary for pre-commit
+- Alternative tools with better GitHub Actions-specific features emerge
+- The problem scope expands beyond preventing broken workflow files
+
+Related resources:
+
+- [actionlint Documentation](https://github.com/rhymond/actionlint)
+- [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
+- [Husky Documentation](https://typicode.github.io/husky/)

package/eslint.config.js

@@ -73,9 +73,9 @@ module.exports = [
     rules: {
       complexity: "error",
       // Enforce maximum lines per function for maintainability
-      "max-lines-per-function": ["error", { max: 90, skipBlankLines: true, skipComments: true }],
+      "max-lines-per-function": ["error", { max: 80, skipBlankLines: true, skipComments: true }],
       // Enforce maximum lines per file for maintainability
-      "max-lines": ["error", { max: 400, skipBlankLines: true, skipComments: true }],
+      "max-lines": ["error", { max: 350, skipBlankLines: true, skipComments: true }],
     },
   },
   {
@@ -90,9 +90,9 @@ module.exports = [
     rules: {
       complexity: "error",
       // Enforce maximum lines per function for maintainability
-      "max-lines-per-function": ["error", { max: 90, skipBlankLines: true, skipComments: true }],
+      "max-lines-per-function": ["error", { max: 80, skipBlankLines: true, skipComments: true }],
       // Enforce maximum lines per file for maintainability
-      "max-lines": ["error", { max: 400, skipBlankLines: true, skipComments: true }],
+      "max-lines": ["error", { max: 350, skipBlankLines: true, skipComments: true }],
     },
   },
   {

package/lib/tests/{basic.test.js → plugin-setup.test.js}

@@ -38,7 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
  */
-const index_1 = __importStar(require("../lib/index"));
+const index_1 = __importStar(require("../src/index"));
 describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
     it("[REQ-PLUGIN-STRUCTURE] plugin exports rules and configs", () => {
         expect(index_1.rules).toBeDefined();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/tests/{basic.test.ts → plugin-setup.test.ts}

@@ -3,7 +3,7 @@
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
  */
-import plugin, { rules, configs } from "../lib/index";
+import plugin, { rules, configs } from "../src/index";
 
 describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
   it("[REQ-PLUGIN-STRUCTURE] plugin exports rules and configs", () => {

package/user-docs/migration-guide.md

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

package/lib/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * ESLint Traceability Plugin
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
- */
-export declare const rules: Record<string, unknown>;
-export declare const configs: {
-  recommended: {
-    rules: {};
-  }[];
-  strict: {
-    rules: {};
-  }[];
-};
-declare const _default: {
-  rules: Record<string, unknown>;
-  configs: {
-    recommended: {
-      rules: {};
-    }[];
-    strict: {
-      rules: {};
-    }[];
-  };
-};
-export default _default;

package/lib/index.js

@@ -1,11 +0,0 @@
-"use strict";
-/**
- * ESLint Traceability Plugin
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
- */
-const plugin = require("./src/index.js");
-
-module.exports = plugin;
-module.exports.rules = plugin.rules;
-module.exports.configs = plugin.configs;

package/lib/tests/integration/file-validation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/lib/tests/integration/file-validation.test.js

@@ -1,71 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Integration tests for file-validation rules via ESLint CLI
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-PERFORMANCE-OPTIMIZATION - Verify CLI integration of valid-story-reference and valid-req-reference rules
- */
-const child_process_1 = require("child_process");
-const path_1 = __importDefault(require("path"));
-// Ensure ESLint CLI uses built plugin
-const eslintBin = path_1.default.resolve(__dirname, "../../node_modules/.bin/eslint");
-const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
-describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATION)", () => {
-    function runLint(code, rules) {
-        const ruleArgs = ["--rule", "no-unused-vars:off"];
-        for (const r of rules) {
-            ruleArgs.push("--rule", r);
-        }
-        return (0, child_process_1.spawnSync)("node", [
-            eslintBin,
-            "--no-config-lookup",
-            "--config",
-            configPath,
-            "--stdin",
-            "--stdin-filename",
-            "foo.js",
-            ...ruleArgs,
-        ], {
-            encoding: "utf-8",
-            input: code,
-        });
-    }
-    it("[REQ-FILE-EXISTENCE] reports missing story file via CLI", () => {
-        // Arrange
-        const code = "// @story docs/stories/missing-file.story.md";
-        // Act
-        const res = runLint(code, ["traceability/valid-story-reference:error"]);
-        // Assert
-        expect(res.status).toBe(1);
-        expect(res.stdout).toContain("Story file");
-    });
-    it("[REQ-EXTENSION] reports invalid extension via CLI", () => {
-        // Arrange
-        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.md";
-        // Act
-        const res = runLint(code, ["traceability/valid-story-reference:error"]);
-        // Assert
-        expect(res.status).toBe(1);
-        expect(res.stdout).toContain("Invalid story file extension");
-    });
-    it("[REQ-DEEP-PARSE] reports missing requirement via CLI", () => {
-        // Arrange
-        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-UNKNOWN";
-        // Act
-        const res = runLint(code, ["traceability/valid-req-reference:error"]);
-        // Assert
-        expect(res.status).toBe(1);
-        expect(res.stdout).toContain("Requirement 'REQ-UNKNOWN' not found");
-    });
-    it("[REQ-DEEP-MATCH] valid story and requirement via CLI", () => {
-        // Arrange
-        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-PLUGIN-STRUCTURE";
-        // Act
-        const res = runLint(code, ["traceability/valid-req-reference:error"]);
-        // Assert
-        expect(res.status).toBe(0);
-    });
-});

package/lib/tests/integration/plugin-validation.test.d.ts

@@ -1 +0,0 @@
-export {};