eslint-plugin-traceability 1.0.3 → 1.0.5

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/conventional-commits-guide.md

@@ -0,0 +1,185 @@
+# Conventional Commits Guide
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) to enable automated semantic versioning and changelog generation through semantic-release.
+
+## Commit Message Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types and Version Impact
+
+### `feat`: New Features (Minor Version)
+
+- Adds new functionality
+- Results in a **minor** version increment (e.g., 1.0.0 → 1.1.0)
+
+Examples:
+
+```bash
+feat: add new validation rule for story references
+feat(rules): implement require-branch-annotation rule
+feat: add CLI integration for batch processing
+```
+
+### `fix`: Bug Fixes (Patch Version)
+
+- Fixes existing functionality
+- Results in a **patch** version increment (e.g., 1.0.0 → 1.0.1)
+
+Examples:
+
+```bash
+fix: resolve annotation parsing for multiline comments
+fix(validation): handle edge case in reference checking
+fix: prevent false positives in story reference detection
+```
+
+### Breaking Changes (Major Version)
+
+- Any commit with `!` after the type or `BREAKING CHANGE:` in footer
+- Results in a **major** version increment (e.g., 1.0.0 → 2.0.0)
+
+Examples:
+
+```bash
+feat!: change API interface for rule configuration
+fix!: remove deprecated annotation format support
+
+feat: add new validation options
+
+BREAKING CHANGE: The `allowUnresolved` option has been removed.
+Use `strict: false` instead.
+```
+
+### Other Types (No Version Change)
+
+These don't trigger releases but appear in changelog:
+
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring without functional changes
+- `test`: Adding or updating tests
+- `chore`: Build process, auxiliary tools, or maintenance
+- `perf`: Performance improvements
+- `ci`: CI/CD configuration changes
+
+Examples:
+
+```bash
+docs: update README with installation instructions
+test: add unit tests for validation rules
+chore: update dependencies to latest versions
+ci: configure semantic-release for automated publishing
+```
+
+## Scopes (Optional)
+
+Use scopes to specify what part of the codebase is affected:
+
+- `rules`: ESLint rule implementations
+- `maintenance`: Maintenance scripts and utilities
+- `cli`: Command-line integration tools
+- `config`: Configuration and setup files
+- `deps`: Dependency updates
+
+Examples:
+
+```bash
+feat(rules): add valid-annotation-format rule
+fix(maintenance): resolve batch processing memory leak
+docs(config): add ESLint 9 setup guide
+```
+
+## Best Practices
+
+### Commit Message Guidelines
+
+1. **Use imperative mood**: "add feature" not "added feature"
+2. **Keep subject under 50 characters**: For better git log readability
+3. **Capitalize the subject line**: Start with capital letter
+4. **No period at the end**: Of the subject line
+5. **Explain what and why**: In the body, not how
+
+### When to Use Each Type
+
+**Use `feat` when:**
+
+- Adding new ESLint rules
+- Adding new maintenance utilities
+- Adding new configuration options
+- Adding new CLI commands or features
+
+**Use `fix` when:**
+
+- Fixing rule logic or false positives/negatives
+- Fixing crashes or runtime errors
+- Fixing configuration issues
+- Fixing documentation errors
+
+**Use `refactor` when:**
+
+- Improving code structure without changing behavior
+- Renaming variables or functions
+- Extracting common functionality
+- Simplifying complex logic
+
+**Use `docs` when:**
+
+- Updating README, guides, or API documentation
+- Adding code comments or JSDoc
+- Updating examples or migration guides
+
+### Example Workflow
+
+```bash
+# New feature
+git commit -m "feat(rules): add require-story-annotation rule
+
+Implements validation to ensure all functions have @story annotations
+linking them to user stories for traceability.
+
+Resolves: #123"
+
+# Bug fix
+git commit -m "fix: resolve false positive in annotation parsing
+
+The regex pattern was incorrectly matching inline comments.
+Updated to only match block comments that start at beginning of line."
+
+# Breaking change
+git commit -m "feat!: change rule configuration schema
+
+BREAKING CHANGE: Rule options now use 'patterns' instead of 'pattern'.
+Update your ESLint config:
+- Before: { "pattern": "REQ-*" }
++ After: { "patterns": ["REQ-*"] }"
+```
+
+## Integration with semantic-release
+
+semantic-release analyzes commit messages to:
+
+1. **Determine version bump**: Based on feat/fix/breaking change types
+2. **Generate changelog**: From commit messages and pull request information
+3. **Create git tags**: For each release
+4. **Publish to npm**: Only when changes warrant a release
+
+## Validation
+
+Pre-commit hooks will validate your commit messages follow the conventional format. If you need to bypass validation temporarily (not recommended), use:
+
+```bash
+git commit --no-verify -m "your message"
+```
+
+## Resources
+
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [semantic-release Documentation](https://semantic-release.gitbook.io/)
+- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format)

package/docs/decisions/004-automated-version-bumping-for-ci-cd.md

@@ -1,5 +1,5 @@
 ---
-status: "proposed"
+status: "superseded"
 date: 2025-11-17
 decision-makers: [Development Team]
 consulted:
@@ -9,6 +9,8 @@ consulted:
     Semantic Versioning Specification,
   ]
 informed: [Project Stakeholders, CI/CD Pipeline Maintainers]
+superseded-by: "006-semantic-release-for-automated-publishing"
+superseded-date: "2025-11-17"
 ---
 
 # Automated Version Bumping for CI/CD Publishing

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/)