effect-bdd 0.1.0

package/src/index.ts

@@ -0,0 +1,155 @@
+import { Bdd as bdd } from "./Bdd.ts"
+import type {
+  Capture as Capture_,
+  DocStringArg as DocStringArg_,
+  Feature as Feature_,
+  GherkinCompiler as GherkinCompiler_,
+  Report as Report_,
+  RunError as RunError_,
+  TableArg as TableArg_
+} from "./Bdd.ts"
+import { MatchError as matchError, ParseError as parseError, StepError as stepError } from "./Errors.ts"
+
+/**
+ * Namespace-style API for building and running BDD feature definitions.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export const Bdd = bdd
+
+/**
+ * Type helpers for the {@link Bdd} value namespace.
+ *
+ * @since 4.0.0
+ */
+export declare namespace Bdd {
+  /**
+   * A local immutable feature definition used to interpret scenarios from Gherkin source.
+   *
+   * @since 4.0.0
+   */
+  export type Feature<State, E = never, R = never> = Feature_<State, E, R>
+
+  /**
+   * Result returned after all scenarios pass.
+   *
+   * @since 4.0.0
+   */
+  export type Report = Report_
+
+  /**
+   * Error type returned by `Bdd.run`.
+   *
+   * @since 4.0.0
+   */
+  export type RunError = RunError_
+
+  /**
+   * Service used to compile Gherkin source into executable scenarios.
+   *
+   * @since 4.0.0
+   */
+  export type GherkinCompiler = GherkinCompiler_
+
+  /**
+   * A named capture decoded from step text with a Schema.
+   *
+   * @since 4.0.0
+   */
+  export type Capture<Name extends string, A> = Capture_<Name, A>
+
+  /**
+   * A decoded DataTable argument.
+   *
+   * @since 4.0.0
+   */
+  export type TableArg<A> = TableArg_<A>
+
+  /**
+   * A decoded DocString argument.
+   *
+   * @since 4.0.0
+   */
+  export type DocStringArg<A> = DocStringArg_<A>
+}
+
+/**
+ * Error raised when a Gherkin step cannot be matched or decoded.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export const MatchError = matchError
+
+/**
+ * Error raised when Gherkin source cannot be parsed.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export const ParseError = parseError
+
+/**
+ * Error raised when a matched step implementation fails.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export const StepError = stepError
+
+/**
+ * A named capture decoded from step text with a Schema.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type Capture<Name extends string, A> = Capture_<Name, A>
+
+/**
+ * A decoded DocString argument.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type DocStringArg<A> = DocStringArg_<A>
+
+/**
+ * A local immutable feature definition used to interpret scenarios from Gherkin source.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type Feature<State, E = never, R = never> = Feature_<State, E, R>
+
+/**
+ * Result returned after all scenarios pass.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type Report = Report_
+
+/**
+ * Error type returned by `Bdd.run`.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type RunError = RunError_
+
+/**
+ * Service used to compile Gherkin source into executable scenarios.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type GherkinCompiler = GherkinCompiler_
+
+/**
+ * A decoded DataTable argument.
+ *
+ * @category re-exports
+ * @since 4.0.0
+ */
+export type TableArg<A> = TableArg_<A>

package/src/internal/cli/errors.ts

@@ -0,0 +1,20 @@
+import * as Data from "effect/Data"
+
+/** @internal */
+export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/** @internal */
+export class ModuleLoadError extends Data.TaggedError("ModuleLoadError")<{
+  readonly path: string
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/** @internal */
+export class ReporterError extends Data.TaggedError("ReporterError")<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}

package/src/internal/cli/glob.ts

@@ -0,0 +1,37 @@
+import * as Arr from "effect/Array"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Layer from "effect/Layer"
+import * as Order from "effect/Order"
+import { glob } from "glob"
+import { DiscoveryError } from "./errors.ts"
+
+const resolve = Effect.fnUntraced(function*(patterns: ReadonlyArray<string>) {
+  const paths = yield* Effect.forEach(patterns, resolvePattern)
+  return pipe(
+    paths,
+    Arr.flatten,
+    Arr.dedupe,
+    Arr.sort(Order.String)
+  )
+})
+
+/** @internal */
+export class GlobResolver extends Context.Service<GlobResolver, {
+  readonly resolve: (patterns: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, DiscoveryError>
+}>()("effect-bdd/cli/GlobResolver") {
+  static readonly Live = Layer.succeed(GlobResolver, {
+    resolve
+  })
+}
+
+const resolvePattern = (pattern: string): Effect.Effect<ReadonlyArray<string>, DiscoveryError> =>
+  Effect.tryPromise({
+    try: () => glob(pattern, { absolute: true, nodir: true }),
+    catch: (cause) =>
+      new DiscoveryError({
+        message: `Could not resolve glob pattern "${pattern}"`,
+        cause
+      })
+  })

package/src/internal/cli/loaders.ts

@@ -0,0 +1,100 @@
+import * as Arr from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import { pipe } from "effect/Function"
+import type * as Path from "effect/Path"
+import * as Record_ from "effect/Record"
+import type * as Bdd from "../../Bdd.ts"
+import { DiscoveryError, type ModuleLoadError } from "./errors.ts"
+import { GlobResolver } from "./glob.ts"
+import type { FeatureSource } from "./models.ts"
+import { ModuleLoader } from "./moduleLoader.ts"
+
+/** @internal */
+export const loadFeatureSources: (
+  patterns: ReadonlyArray<string>
+) => Effect.Effect<ReadonlyArray<FeatureSource>, DiscoveryError, FileSystem.FileSystem | GlobResolver> = Effect
+  .fnUntraced(function*(
+    patterns: ReadonlyArray<string>
+  ) {
+    const fs = yield* FileSystem.FileSystem
+    const glob = yield* GlobResolver
+    const paths = yield* nonEmptyPaths(
+      yield* glob.resolve(patterns),
+      "No feature files matched --features"
+    )
+    return yield* Effect.forEach(paths, (path) =>
+      pipe(
+        fs.readFileString(path),
+        Effect.map((source): FeatureSource => ({ path, source })),
+        Effect.mapError((cause) =>
+          new DiscoveryError({
+            message: `Could not read feature file "${path}"`,
+            cause
+          })
+        )
+      ))
+  })
+
+/** @internal */
+export const loadFeatureDefinitions: (
+  patterns: ReadonlyArray<string>
+) => Effect.Effect<
+  ReadonlyArray<Bdd.Feature<unknown, unknown, never>>,
+  DiscoveryError | ModuleLoadError,
+  GlobResolver | ModuleLoader | Path.Path
+> = Effect.fnUntraced(function*(
+  patterns: ReadonlyArray<string>
+) {
+  const glob = yield* GlobResolver
+  const loader = yield* ModuleLoader
+  const paths = yield* nonEmptyPaths(
+    yield* glob.resolve(patterns),
+    "No step definition modules matched --steps"
+  )
+  const definitions = yield* Effect.forEach(paths, (path) =>
+    pipe(
+      loader.load(path),
+      Effect.map(extractFeatureDefinitions)
+    ))
+  return yield* nonEmptyDefinitions(Arr.flatten(definitions))
+})
+
+const nonEmptyPaths = (
+  paths: ReadonlyArray<string>,
+  message: string
+): Effect.Effect<ReadonlyArray<string>, DiscoveryError> =>
+  paths.length === 0
+    ? Effect.fail(new DiscoveryError({ message }))
+    : Effect.succeed(paths)
+
+const nonEmptyDefinitions = (
+  definitions: ReadonlyArray<Bdd.Feature<unknown, unknown, never>>
+): Effect.Effect<ReadonlyArray<Bdd.Feature<unknown, unknown, never>>, DiscoveryError> =>
+  definitions.length === 0
+    ? Effect.fail(new DiscoveryError({ message: "No Bdd.Feature exports found in matched step definition modules" }))
+    : Effect.succeed(definitions)
+
+const extractFeatureDefinitions = (
+  module: Record<string, unknown>
+): ReadonlyArray<Bdd.Feature<unknown, unknown, never>> =>
+  pipe(
+    Record_.values(module),
+    Arr.filter(isFeatureDefinition)
+  )
+
+const isFeatureDefinition = (value: unknown): value is Bdd.Feature<unknown, unknown, never> => {
+  if (typeof value !== "object" || value === null) {
+    return false
+  }
+  const candidate = value as {
+    readonly _tag?: unknown
+    readonly initial?: unknown
+    readonly name?: unknown
+    readonly transitions?: unknown
+  }
+  return candidate._tag === "Feature" &&
+    "initial" in candidate &&
+    typeof candidate.name === "string" &&
+    Array.isArray(candidate.transitions)
+}

package/src/internal/cli/models.ts

@@ -0,0 +1,118 @@
+import type { PickleStep } from "@cucumber/messages"
+import type * as Bdd from "../../Bdd.ts"
+import type * as Parser from "../parser.ts"
+import type * as CoreRunner from "../runner.ts"
+
+/** @internal */
+export interface FeatureSource {
+  readonly path: string
+  readonly source: string
+}
+
+/** @internal */
+export interface ScenarioTask {
+  readonly featurePath: string
+  readonly core: CoreRunner.ScenarioTask<unknown, unknown, never>
+}
+
+/** @internal */
+export type ScenarioOutcome =
+  | {
+    readonly _tag: "Passed"
+    readonly steps: number
+  }
+  | {
+    readonly _tag: "Failed"
+    readonly error: Bdd.RunError
+  }
+
+/** @internal */
+export interface ScenarioResult {
+  readonly task: ScenarioTask
+  readonly outcome: ScenarioOutcome
+  readonly durationMillis: number
+}
+
+/** @internal */
+export interface RunSummary {
+  readonly features: number
+  readonly total: number
+  readonly passed: number
+  readonly failed: number
+  readonly durationMillis: number
+}
+
+/** @internal */
+export type CliDiagnostic =
+  | {
+    readonly _tag: "UnmatchedFeature"
+    readonly featurePath: string
+    readonly featureName: string
+    readonly line: number
+    readonly message: string
+  }
+  | {
+    readonly _tag: "UnmatchedStep"
+    readonly featurePath: string
+    readonly featureName: string
+    readonly scenarioName: string
+    readonly scenarioLine: number
+    readonly step: PickleStep
+    readonly source: Parser.SourceIndex
+    readonly reason: "NoMatch" | "WrongKeyword" | "MultipleMatches"
+    readonly candidates: ReadonlyArray<string>
+    readonly message: string
+  }
+  | {
+    readonly _tag: "UnmatchedScenario"
+    readonly featurePath: string
+    readonly featureName: string
+    readonly scenarioName: string
+    readonly scenarioLine: number
+    readonly message: string
+  }
+  | {
+    readonly _tag: "UnusedFeatureDefinition"
+    readonly featureName: string
+    readonly message: string
+  }
+  | {
+    readonly _tag: "UnusedStepDefinition"
+    readonly featureName: string
+    readonly expression: string
+    readonly kind: string
+    readonly message: string
+  }
+
+/** @internal */
+export interface CliRunResult {
+  readonly results: ReadonlyArray<ScenarioResult>
+  readonly diagnostics: ReadonlyArray<CliDiagnostic>
+  readonly summary: RunSummary
+}
+
+/** @internal */
+export interface CliFilters {
+  readonly tags: ReadonlyArray<string>
+  readonly names: ReadonlyArray<string>
+  readonly failFast: boolean
+}
+
+/** @internal */
+export interface CliOptions {
+  readonly features: ReadonlyArray<string>
+  readonly steps: ReadonlyArray<string>
+  readonly reporters: ReadonlyArray<ReporterName>
+  readonly outputFiles: {
+    readonly text?: string
+    readonly html?: string
+    readonly json?: string
+    readonly junit?: string
+  }
+  readonly verbose: boolean
+  readonly filters: CliFilters
+  readonly parallel: number
+}
+
+/** @internal */
+export type ReporterName = "text" | "html" | "json" | "junit"

package/src/internal/cli/moduleLoader.ts

@@ -0,0 +1,41 @@
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import { pathToFileURL } from "node:url"
+import { ModuleLoadError } from "./errors.ts"
+
+const load = Effect.fnUntraced(function*(path: string) {
+  const pathService = yield* Path.Path
+  const resolved = pathService.resolve(path)
+  return yield* Effect.tryPromise({
+    try: () => import(pathToFileURL(resolved).href) as Promise<Record<string, unknown>>,
+    catch: (cause) => moduleLoadError(resolved, cause)
+  })
+})
+
+/** @internal */
+export class ModuleLoader extends Context.Service<ModuleLoader, {
+  readonly load: (path: string) => Effect.Effect<Record<string, unknown>, ModuleLoadError, Path.Path>
+}>()("effect-bdd/cli/ModuleLoader") {
+  static readonly Live = Layer.succeed(ModuleLoader, {
+    load
+  })
+}
+
+const moduleLoadError = (path: string, cause: unknown): ModuleLoadError => {
+  const reason = causeMessage(cause)
+  const isTsLoaderFailure = reason.includes("Unknown file extension") && reason.includes(".ts")
+  return new ModuleLoadError({
+    path,
+    message: isTsLoaderFailure
+      ? `Could not load TypeScript step module "${path}". Register a TypeScript loader when running on Node, for example: node --import tsx ./node_modules/.bin/effect-bdd`
+      : `Could not load step module "${path}": ${reason}`,
+    cause
+  })
+}
+
+const causeMessage = (cause: unknown): string =>
+  typeof cause === "object" && cause !== null && "message" in cause && typeof cause.message === "string"
+    ? cause.message
+    : String(cause)