@step-forge/step-forge 0.0.7-beta.7 → 0.0.8

package/package.json

@@ -1,28 +1,37 @@
 {
   "name": "@step-forge/step-forge",
-  "version": "0.0.7-beta.7",
+  "version": "0.0.8",
+  "module": "./dist/step-forge.js",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/step-forge.js",
-      "require": "./dist/step-forge.cjs"
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/step-forge.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/step-forge.js"
+      }
+    },
+    "./analyzer": {
+      "types": "./dist/analyzer.d.ts",
+      "import": "./dist/analyzer.js"
     },
-    "./package.json": "./package.json"
+    "./dist/": {
+      "import": "./dist/"
+    }
   },
-  "main": "./dist/step-forge.cjs",
-  "module": "./dist/step-forge.js",
-  "types": "./dist/types/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "bin": {
+    "step-forge-analyze": "./dist/analyzer-cli.js"
+  },
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "dev": "vite --host",
-    "build": "rimraf dist && tsc && vite build && dts-bundle-generator --config ./dts-bundle-generator.config.cjs",
-    "test:cucumber": "NODE_ENV=test NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" TS_NODE_PROJECT=./tsconfig.cucumber.json cucumber-js -p default",
-    "test:ci": "NODE_ENV=test cucumber-js -p ci",
-    "test": "NODE_ENV=test NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" TS_NODE_PROJECT=./tsconfig.cucumber.json cucumber-js -p default 2> /dev/null",
-    "test:debug": "NODE_ENV=test PORT=7888 cucumber-js -p all",
+    "build": "rm -rf build && tsc && rolldown -c && dts-bundle-generator --config ./dts-bundle-generator.config.cjs && cp build/dist/index.d.ts build/dist/index.d.cts && cp package.json build/",
+    "test:cucumber": "NODE_ENV=test NODE_OPTIONS='--import tsx' cucumber-js -p default",
+    "test:ci": "NODE_ENV=test NODE_OPTIONS='--import tsx' cucumber-js -p ci",
+    "test": "NODE_ENV=test PORT=7888 LOG_LEVEL=none NODE_OPTIONS='--import tsx' cucumber-js -p all 2> /dev/null",
+    "test:debug": "NODE_ENV=test PORT=7888 NODE_OPTIONS='--import tsx' cucumber-js -p all",
     "lint": "eslint . --ext .ts",
     "format": "prettier . --write"
   },
@@ -33,23 +42,29 @@
     "@types/node": "^22.10.2",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
-    "@vitest/coverage-v8": "^2.0.4",
-    "copyfiles": "^2.4.1",
     "dts-bundle-generator": "^9.5.1",
     "earl": "^1.3.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.2.1",
     "prettier": "^3.3.3",
-    "rimraf": "^6.0.1",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.7.2",
-    "vite": "^5.3.5",
-    "vitest": "^2.0.4"
+    "tsx": "^4.19.0",
+    "rolldown": "^1.0.0-rc.3",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@cucumber/cucumber": "^11.1.1",
+    "@cucumber/cucumber": "^12.6.0",
+    "@cucumber/cucumber-expressions": "^18.1.0",
+    "@cucumber/gherkin": "^37.0.1",
+    "@cucumber/messages": "^24.1.0",
     "lodash": "^4.17.21"
   }
 }

package/rolldown.config.mjs

@@ -0,0 +1,45 @@
+import { defineConfig } from "rolldown";
+
+const allExternal = [
+  "@cucumber/cucumber",
+  "@cucumber/gherkin",
+  "@cucumber/messages",
+  "@cucumber/cucumber-expressions",
+  "lodash",
+  "typescript",
+  /^node:/,
+];
+
+export default defineConfig([
+  {
+    input: "./src/index.ts",
+    output: {
+      file: "./build/dist/step-forge.js",
+      format: "esm",
+      sourcemap: true,
+    },
+    external: allExternal,
+  },
+  {
+    input: "./src/index.ts",
+    output: {
+      file: "./build/dist/step-forge.cjs",
+      format: "cjs",
+      sourcemap: true,
+    },
+    external: allExternal,
+  },
+  {
+    input: {
+      analyzer: "./src/analyzer/index.ts",
+      "analyzer-cli": "./src/analyzer/cli.ts",
+    },
+    output: {
+      dir: "./build/dist",
+      format: "esm",
+      sourcemap: true,
+      entryFileNames: "[name].js",
+    },
+    external: allExternal,
+  },
+]);

package/src/analyzer/cli.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { analyze } from "./index.js";
+import type { AnalyzerConfig, Diagnostic } from "./types.js";
+
+function parseArgs(args: string[]): AnalyzerConfig {
+  const config: AnalyzerConfig = {
+    stepFiles: [],
+    featureFiles: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if ((arg === "--steps" || arg === "-s") && next) {
+      config.stepFiles.push(next);
+      i++;
+    } else if ((arg === "--features" || arg === "-f") && next) {
+      config.featureFiles.push(next);
+      i++;
+    } else if (arg === "--tsconfig" && next) {
+      config.tsConfigPath = next;
+      i++;
+    } else if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+  }
+
+  return config;
+}
+
+function printUsage() {
+  console.log(`Usage: step-forge-analyze [options]
+
+Options:
+  -s, --steps <glob>      Glob pattern for step definition files (repeatable)
+  -f, --features <glob>   Glob pattern for feature files (repeatable)
+  --tsconfig <path>       Path to tsconfig.json (default: auto-detect)
+  -h, --help              Show this help message
+
+Example:
+  step-forge-analyze --steps "features/steps/**/*.ts" --features "features/**/*.feature"
+`);
+}
+
+function formatDiagnostic(diag: Diagnostic): string {
+  const location = `${diag.file}:${diag.range.startLine}:${diag.range.startColumn}`;
+  return `${location} - ${diag.severity}: ${diag.message}`;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const config = parseArgs(args);
+
+  if (config.stepFiles.length === 0 || config.featureFiles.length === 0) {
+    console.error(
+      "Error: Both --steps and --features are required.\n"
+    );
+    printUsage();
+    process.exit(1);
+  }
+
+  const diagnostics = await analyze(config);
+
+  if (diagnostics.length === 0) {
+    console.log("No issues found.");
+    process.exit(0);
+  }
+
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  const warnings = diagnostics.filter((d) => d.severity === "warning");
+
+  for (const diag of diagnostics) {
+    console.log(formatDiagnostic(diag));
+  }
+
+  console.log(
+    `\nFound ${errors.length} error(s) and ${warnings.length} warning(s).`
+  );
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+// Only run when invoked directly (not when imported by Cucumber or other tools)
+const isDirectRun =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith("analyzer-cli.js") ||
+  process.argv[1]?.endsWith("analyzer-cli.ts");
+
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error("Analyzer failed:", err);
+    process.exit(1);
+  });
+}

package/src/analyzer/gherkinParser.ts

@@ -0,0 +1,175 @@
+import * as fs from "node:fs";
+import { GherkinClassicTokenMatcher, Parser, AstBuilder } from "@cucumber/gherkin";
+import * as messages from "@cucumber/messages";
+import { ParsedScenario, ParsedStep } from "./types.js";
+
+type GherkinKeyword = "Given" | "When" | "Then" | "And" | "But";
+
+export function parseFeatureFiles(filePaths: string[]): ParsedScenario[] {
+  const scenarios: ParsedScenario[] = [];
+
+  for (const filePath of filePaths) {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = parseFeatureContent(content, filePath);
+    scenarios.push(...parsed);
+  }
+
+  return scenarios;
+}
+
+export function parseFeatureContent(
+  content: string,
+  filePath: string
+): ParsedScenario[] {
+  const newId = messages.IdGenerator.uuid();
+  const builder = new AstBuilder(newId);
+  const matcher = new GherkinClassicTokenMatcher();
+  const parser = new Parser(builder, matcher);
+
+  const gherkinDocument: messages.GherkinDocument = parser.parse(content);
+  const feature = gherkinDocument.feature;
+  if (!feature) return [];
+
+  // Collect background steps at the feature level
+  const featureBackground: messages.Step[] = [];
+  const scenarios: ParsedScenario[] = [];
+
+  for (const child of feature.children) {
+    if (child.background) {
+      featureBackground.push(...child.background.steps);
+    }
+
+    if (child.scenario) {
+      scenarios.push(
+        ...expandScenario(child.scenario, featureBackground, filePath)
+      );
+    }
+
+    if (child.rule) {
+      // Rules can have their own backgrounds
+      const ruleBackground: messages.Step[] = [...featureBackground];
+      for (const ruleChild of child.rule.children) {
+        if (ruleChild.background) {
+          ruleBackground.push(...ruleChild.background.steps);
+        }
+        if (ruleChild.scenario) {
+          scenarios.push(
+            ...expandScenario(ruleChild.scenario, ruleBackground, filePath)
+          );
+        }
+      }
+    }
+  }
+
+  return scenarios;
+}
+
+function expandScenario(
+  scenario: messages.Scenario,
+  backgroundSteps: messages.Step[],
+  filePath: string
+): ParsedScenario[] {
+  const hasExamples =
+    scenario.examples.length > 0 &&
+    scenario.examples.some((e) => e.tableBody.length > 0);
+
+  if (!hasExamples) {
+    // Regular scenario
+    const bgParsed = convertSteps(backgroundSteps);
+    const scenarioParsed = convertSteps(scenario.steps);
+    const allSteps = resolveEffectiveKeywords([...bgParsed, ...scenarioParsed]);
+
+    return [
+      {
+        name: scenario.name,
+        file: filePath,
+        steps: allSteps,
+      },
+    ];
+  }
+
+  // Scenario Outline — expand with each example row
+  const results: ParsedScenario[] = [];
+  for (const example of scenario.examples) {
+    if (!example.tableHeader || example.tableBody.length === 0) continue;
+    const headers = example.tableHeader.cells.map((c) => c.value);
+
+    for (const row of example.tableBody) {
+      const values = row.cells.map((c) => c.value);
+      const substitution: Record<string, string> = {};
+      headers.forEach((h, i) => {
+        substitution[h] = values[i];
+      });
+
+      const bgParsed = convertSteps(backgroundSteps);
+      const scenarioSteps = convertSteps(scenario.steps).map((step) => ({
+        ...step,
+        text: substituteExampleValues(step.text, substitution),
+      }));
+      const allSteps = resolveEffectiveKeywords([...bgParsed, ...scenarioSteps]);
+
+      results.push({
+        name: `${scenario.name} (${values.join(", ")})`,
+        file: filePath,
+        steps: allSteps,
+      });
+    }
+  }
+
+  return results;
+}
+
+function convertSteps(
+  steps: readonly messages.Step[]
+): Omit<ParsedStep, "effectiveKeyword">[] {
+  return steps.map((step) => ({
+    keyword: normalizeKeyword(step.keyword),
+    text: step.text,
+    line: step.location.line,
+    column: step.location.column ?? 1,
+  }));
+}
+
+function normalizeKeyword(keyword: string): GherkinKeyword {
+  const trimmed = keyword.trim();
+  // Gherkin keywords may include trailing space, e.g. "Given "
+  if (trimmed === "Given") return "Given";
+  if (trimmed === "When") return "When";
+  if (trimmed === "Then") return "Then";
+  if (trimmed === "And") return "And";
+  if (trimmed === "But") return "But";
+  // Fallback: treat as Given (shouldn't happen with valid Gherkin)
+  return "Given";
+}
+
+function resolveEffectiveKeywords(
+  steps: Omit<ParsedStep, "effectiveKeyword">[]
+): ParsedStep[] {
+  let lastEffective: "Given" | "When" | "Then" = "Given";
+
+  return steps.map((step) => {
+    let effectiveKeyword: "Given" | "When" | "Then";
+    if (step.keyword === "And" || step.keyword === "But") {
+      effectiveKeyword = lastEffective;
+    } else {
+      effectiveKeyword = step.keyword as "Given" | "When" | "Then";
+    }
+    lastEffective = effectiveKeyword;
+
+    return {
+      ...step,
+      effectiveKeyword,
+    };
+  });
+}
+
+function substituteExampleValues(
+  text: string,
+  substitution: Record<string, string>
+): string {
+  let result = text;
+  for (const [key, value] of Object.entries(substitution)) {
+    result = result.replace(new RegExp(`<${key}>`, "g"), value);
+  }
+  return result;
+}

package/src/analyzer/index.ts

@@ -0,0 +1,89 @@
+import { glob } from "node:fs/promises";
+import * as path from "node:path";
+import { extractStepDefinitions } from "./stepExtractor.js";
+import { parseFeatureFiles, parseFeatureContent } from "./gherkinParser.js";
+import {
+  matchScenarioSteps,
+  findMatchingDefinitions,
+} from "./stepMatcher.js";
+import { defaultRules, runRules } from "./rules/index.js";
+import type {
+  AnalyzerConfig,
+  AnalysisRule,
+  Diagnostic,
+  StepDefinitionMeta,
+  ParsedScenario,
+  MatchedStep,
+  ParsedStep,
+} from "./types.js";
+
+export type {
+  AnalyzerConfig,
+  AnalysisRule,
+  Diagnostic,
+  StepDefinitionMeta,
+  ParsedScenario,
+  MatchedStep,
+  ParsedStep,
+};
+
+export {
+  extractStepDefinitions,
+  parseFeatureFiles,
+  parseFeatureContent,
+  matchScenarioSteps,
+  findMatchingDefinitions,
+  defaultRules,
+};
+
+export interface AnalyzeOptions {
+  rules?: AnalysisRule[];
+}
+
+export async function analyze(
+  config: AnalyzerConfig,
+  options?: AnalyzeOptions
+): Promise<Diagnostic[]> {
+  const rules = options?.rules ?? defaultRules;
+
+  // 1. Resolve file globs to paths
+  const stepFilePaths = await resolveGlobs(config.stepFiles);
+  const featureFilePaths = await resolveGlobs(config.featureFiles);
+
+  if (stepFilePaths.length === 0) {
+    return [];
+  }
+  if (featureFilePaths.length === 0) {
+    return [];
+  }
+
+  // 2. Extract step metadata from step files
+  const stepDefinitions = extractStepDefinitions(
+    stepFilePaths,
+    config.tsConfigPath
+  );
+
+  // 3. Parse feature files
+  const scenarios = parseFeatureFiles(featureFilePaths);
+
+  // 4. For each scenario, match steps and run rules
+  const diagnostics: Diagnostic[] = [];
+  for (const scenario of scenarios) {
+    const matchedSteps = matchScenarioSteps(scenario, stepDefinitions);
+    const scenarioDiags = runRules(rules, scenario, matchedSteps);
+    diagnostics.push(...scenarioDiags);
+  }
+
+  return diagnostics;
+}
+
+async function resolveGlobs(patterns: string[]): Promise<string[]> {
+  const files: string[] = [];
+  for (const pattern of patterns) {
+    for await (const file of glob(pattern)) {
+      files.push(path.resolve(file));
+    }
+  }
+  // Deduplicate
+  return [...new Set(files)];
+}

package/src/analyzer/rules/ambiguousStepRule.ts

@@ -0,0 +1,36 @@
+import {
+  AnalysisRule,
+  Diagnostic,
+  MatchedStep,
+  ParsedScenario,
+} from "../types.js";
+
+export const ambiguousStepRule: AnalysisRule = {
+  name: "ambiguous-step",
+
+  check(
+    scenario: ParsedScenario,
+    matchedSteps: MatchedStep[]
+  ): Diagnostic[] {
+    return matchedSteps
+      .filter((step) => step.definitions.length > 1)
+      .map((step) => {
+        const locations = step.definitions
+          .map((d) => `${d.sourceFile}:${d.line}`)
+          .join(", ");
+        return {
+          file: scenario.file,
+          range: {
+            startLine: step.line,
+            startColumn: step.column,
+            endLine: step.line,
+            endColumn: step.column + step.text.length,
+          },
+          severity: "error" as const,
+          message: `Step "${step.text}" matches multiple step definitions: ${locations}`,
+          rule: "ambiguous-step",
+          source: "step-forge" as const,
+        };
+      });
+  },
+};

package/src/analyzer/rules/dependencyRule.ts

@@ -0,0 +1,71 @@
+import {
+  AnalysisRule,
+  Diagnostic,
+  MatchedStep,
+  ParsedScenario,
+} from "../types.js";
+
+export const dependencyRule: AnalysisRule = {
+  name: "dependency-check",
+
+  check(
+    scenario: ParsedScenario,
+    matchedSteps: MatchedStep[]
+  ): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [];
+    const produced = {
+      given: new Set<string>(),
+      when: new Set<string>(),
+      then: new Set<string>(),
+    };
+
+    for (const step of matchedSteps) {
+      if (step.definitions.length !== 1) continue;
+
+      const { dependencies, produces, stepType } = step.definitions[0];
+
+      // Collect all missing required dependencies for this step
+      const missing: Record<string, string[]> = {};
+      for (const phase of ["given", "when", "then"] as const) {
+        for (const [key, requirement] of Object.entries(dependencies[phase])) {
+          if (requirement === "required" && !produced[phase].has(key)) {
+            if (!missing[phase]) {
+              missing[phase] = [];
+            }
+            missing[phase].push(key);
+          }
+        }
+      }
+
+      if (Object.keys(missing).length > 0) {
+        const lines = Object.entries(missing).map(
+          ([phase, keys]) =>
+            `${phase.charAt(0).toUpperCase() + phase.slice(1)}: ${keys.map((k) => `${phase}.${k}`).join(", ")}`
+        );
+        const message =
+          "Missing required dependencies:\n" + lines.join("\n");
+
+        diagnostics.push({
+          file: scenario.file,
+          range: {
+            startLine: step.line,
+            startColumn: step.column,
+            endLine: step.line,
+            endColumn: step.column + step.text.length,
+          },
+          severity: "error",
+          message,
+          rule: "dependency-check",
+          source: "step-forge",
+        });
+      }
+
+      // Add produced keys for this step
+      for (const key of produces) {
+        produced[stepType].add(key);
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/analyzer/rules/index.ts

@@ -0,0 +1,23 @@
+import {
+  AnalysisRule,
+  Diagnostic,
+  MatchedStep,
+  ParsedScenario,
+} from "../types.js";
+import { ambiguousStepRule } from "./ambiguousStepRule.js";
+import { dependencyRule } from "./dependencyRule.js";
+import { undefinedStepRule } from "./undefinedStepRule.js";
+
+export const defaultRules: AnalysisRule[] = [
+  undefinedStepRule,
+  ambiguousStepRule,
+  dependencyRule,
+];
+
+export function runRules(
+  rules: AnalysisRule[],
+  scenario: ParsedScenario,
+  matchedSteps: MatchedStep[]
+): Diagnostic[] {
+  return rules.flatMap((rule) => rule.check(scenario, matchedSteps));
+}

package/src/analyzer/rules/undefinedStepRule.ts

@@ -0,0 +1,31 @@
+import {
+  AnalysisRule,
+  Diagnostic,
+  MatchedStep,
+  ParsedScenario,
+} from "../types.js";
+
+export const undefinedStepRule: AnalysisRule = {
+  name: "undefined-step",
+
+  check(
+    scenario: ParsedScenario,
+    matchedSteps: MatchedStep[]
+  ): Diagnostic[] {
+    return matchedSteps
+      .filter((step) => step.definitions.length === 0)
+      .map((step) => ({
+        file: scenario.file,
+        range: {
+          startLine: step.line,
+          startColumn: step.column,
+          endLine: step.line,
+          endColumn: step.column + step.text.length,
+        },
+        severity: "error" as const,
+        message: `Step "${step.text}" does not match any step definition`,
+        rule: "undefined-step",
+        source: "step-forge" as const,
+      }));
+  },
+};