@questi0nm4rk/feats 1.0.0

package/dist/src/assertions/config-assertions.d.ts

@@ -0,0 +1,5 @@
+export interface AssertConfigOpts {
+    readonly format?: "json" | "toml" | "yaml";
+    readonly subset?: boolean;
+}
+export declare function assertConfig(filePath: string, expected: Record<string, unknown>, opts?: AssertConfigOpts): void;

package/dist/src/assertions/output-assertions.d.ts

@@ -0,0 +1,9 @@
+import type { CLIResult } from "@/cli/cli-result";
+export interface OutputExpectations {
+    readonly stdout?: string | RegExp;
+    readonly stderr?: string | RegExp;
+    readonly exitCode?: number;
+    readonly contains?: string;
+    readonly notContains?: string;
+}
+export declare function assertOutput(result: CLIResult, expectations: OutputExpectations): void;

package/dist/src/cli/cli-result.d.ts

@@ -0,0 +1,6 @@
+export interface CLIResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly timedOut: boolean;
+}

package/dist/src/cli/cli-runner.d.ts

@@ -0,0 +1,8 @@
+import type { CLIResult } from "@/cli/cli-result";
+export interface RunCliOpts {
+    readonly cwd?: string;
+    readonly timeout?: number;
+    readonly env?: Record<string, string>;
+    readonly stdin?: string;
+}
+export declare function runCli(command: string, args?: string[], opts?: RunCliOpts): Promise<CLIResult>;

package/dist/src/feats.d.ts

@@ -0,0 +1,16 @@
+export { assertConfig } from "./assertions/config-assertions";
+export { assertOutput } from "./assertions/output-assertions";
+export type { CLIResult } from "./cli/cli-result";
+export { runCli } from "./cli/cli-runner";
+export { composeFixtures, setupFixture } from "./fixtures/fixture-manager";
+export type { FixtureProject } from "./fixtures/fixture-project";
+export { loadFeatures, parseFeature } from "./parser/adapter";
+export type { DataTable, Feature, ParsedStep, Scenario, Tag } from "./parser/models";
+export type { SeededRng } from "./random/seeded-rng";
+export { createRng } from "./random/seeded-rng";
+export { defineParameterType } from "./registry/parameter-types";
+export { Given, Step, Then, When } from "./registry/step-registry";
+export type { RunOptions } from "./runner/feature-runner";
+export { runFeatures } from "./runner/feature-runner";
+export { After, Before } from "./runner/hook-runner";
+export type { World, WorldFactory } from "./state/world";

package/dist/src/fixtures/fixture-manager.d.ts

@@ -0,0 +1,6 @@
+import type { FixtureProject } from "@/fixtures/fixture-project";
+export interface FixtureOpts {
+    readonly fixtureDir: string;
+}
+export declare function setupFixture(name: string, opts: FixtureOpts): Promise<FixtureProject>;
+export declare function composeFixtures(names: string[], opts: FixtureOpts): Promise<FixtureProject>;

package/dist/src/fixtures/fixture-project.d.ts

@@ -0,0 +1,12 @@
+import type { CLIResult } from "@/cli/cli-result";
+export interface FixtureProject {
+    readonly dir: string;
+    run(command: string, args?: string[]): Promise<CLIResult>;
+    hasFile(path: string): boolean;
+    readFile(path: string): Promise<string>;
+    readJson(path: string): Promise<unknown>;
+    readToml(path: string): Promise<unknown>;
+    listFiles(glob?: string): Promise<string[]>;
+    cleanup(): Promise<void>;
+}
+export declare function createFixtureProject(dir: string): FixtureProject;

package/dist/src/parser/adapter.d.ts

@@ -0,0 +1,5 @@
+import type { Feature } from "@/parser/models";
+export declare function parseFeature(source: string, uri: string): Feature;
+export declare function loadFeatures(globPattern: string, opts?: {
+    cwd?: string;
+}): Promise<Feature[]>;

package/dist/src/parser/models.d.ts

@@ -0,0 +1,35 @@
+export interface Tag {
+    readonly name: string;
+}
+export interface StepLocation {
+    readonly uri: string;
+    readonly line: number;
+}
+export interface DataTable {
+    readonly rows: readonly (readonly string[])[];
+    asObjects(): Record<string, string>[];
+    asLists(): string[][];
+}
+export interface ParsedStep {
+    readonly keyword: "Given" | "When" | "Then" | "And" | "But";
+    readonly text: string;
+    readonly dataTable: DataTable | undefined;
+    readonly docString: string | undefined;
+    readonly location: StepLocation;
+}
+export interface Scenario {
+    readonly name: string;
+    readonly tags: readonly Tag[];
+    readonly steps: readonly ParsedStep[];
+}
+export interface Feature {
+    readonly name: string;
+    readonly description: string;
+    readonly tags: readonly Tag[];
+    readonly background: {
+        readonly steps: readonly ParsedStep[];
+    } | undefined;
+    readonly scenarios: readonly Scenario[];
+    readonly uri: string;
+}
+export declare function createDataTable(rows: readonly (readonly string[])[]): DataTable;

package/dist/src/plugin/bun-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { BunPlugin } from "bun";
+declare const featsPlugin: BunPlugin;
+export default featsPlugin;

package/dist/src/random/seeded-rng.d.ts

@@ -0,0 +1,8 @@
+export interface SeededRng {
+    readonly seed: number;
+    nextInt(min: number, max: number): number;
+    pick<T>(items: readonly T[]): T;
+    shuffle<T>(items: readonly T[]): T[];
+    sample<T>(items: readonly T[], count: number): T[];
+}
+export declare function createRng(seed?: number): SeededRng;

package/dist/src/registry/expression-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { StepDefinition } from "@/registry/step-definition";
+export interface MatchResult {
+    readonly definition: StepDefinition;
+    readonly args: readonly unknown[];
+}
+export declare function matchStep(definitions: readonly StepDefinition[], stepText: string): MatchResult;

package/dist/src/registry/parameter-types.d.ts

@@ -0,0 +1,8 @@
+import { ParameterTypeRegistry } from "@cucumber/cucumber-expressions";
+export declare function getParameterTypeRegistry(): ParameterTypeRegistry;
+export declare function clearParameterTypeRegistry(): void;
+export declare function defineParameterType(opts: {
+    name: string;
+    regexp: RegExp;
+    transformer: (value: string) => unknown;
+}): void;

package/dist/src/registry/step-definition.d.ts

@@ -0,0 +1,7 @@
+import type { World } from "@/state/world";
+export type StepCallback<W extends World = World> = (world: W, ...args: unknown[]) => Promise<void> | void;
+export interface StepDefinition<W extends World = World> {
+    readonly keyword: "Given" | "When" | "Then" | "Step";
+    readonly pattern: string;
+    readonly callback: StepCallback<W>;
+}

package/dist/src/registry/step-registry.d.ts

@@ -0,0 +1,14 @@
+import type { StepCallback, StepDefinition } from "@/registry/step-definition";
+import type { World } from "@/state/world";
+export declare class StepRegistry {
+    private readonly definitions;
+    add(definition: StepDefinition): void;
+    getAll(): readonly StepDefinition[];
+    clear(): void;
+}
+export declare function getRegistry(): StepRegistry;
+export declare function clearRegistry(): void;
+export declare function Given<W extends World = World>(pattern: string, callback: StepCallback<W>): void;
+export declare function When<W extends World = World>(pattern: string, callback: StepCallback<W>): void;
+export declare function Then<W extends World = World>(pattern: string, callback: StepCallback<W>): void;
+export declare function Step<W extends World = World>(pattern: string, callback: StepCallback<W>): void;

package/dist/src/reporting/error-formatter.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedStep } from "@/parser/models";
+export declare function formatStepError(step: ParsedStep, error: unknown): string;

package/dist/src/reporting/pending-steps.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedStep } from "@/parser/models";
+export declare function generateStepSnippet(step: ParsedStep): string;

package/dist/src/runner/feature-runner.d.ts

@@ -0,0 +1,9 @@
+import type { Feature } from "@/parser/models";
+import type { HookDefinition } from "@/runner/hook-runner";
+import type { WorldFactory } from "@/state/world";
+export interface RunOptions {
+    worldFactory?: WorldFactory;
+    tagFilter?: string;
+}
+export declare function runFeatures(features: readonly Feature[], opts?: RunOptions): void;
+export type { HookDefinition };

package/dist/src/runner/hook-runner.d.ts

@@ -0,0 +1,12 @@
+import type { World } from "@/state/world";
+export interface HookDefinition {
+    readonly tagFilter: string | undefined;
+    readonly callback: (world: World) => Promise<void> | void;
+}
+export declare function Before(callback: (world: World) => Promise<void> | void): void;
+export declare function Before(tagFilter: string, callback: (world: World) => Promise<void> | void): void;
+export declare function After(callback: (world: World) => Promise<void> | void): void;
+export declare function After(tagFilter: string, callback: (world: World) => Promise<void> | void): void;
+export declare function getBeforeHooks(): HookDefinition[];
+export declare function getAfterHooks(): HookDefinition[];
+export declare function clearHooks(): void;

package/dist/src/runner/scenario-runner.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedStep } from "@/parser/models";
+import type { World } from "@/state/world";
+export declare function executeStep(world: World, step: ParsedStep): Promise<void>;

package/dist/src/runner/tag-filter.d.ts

@@ -0,0 +1,2 @@
+import type { Tag } from "@/parser/models";
+export declare function matchesTagFilter(tags: readonly Tag[], filterExpr: string): boolean;

package/dist/src/state/world.d.ts

@@ -0,0 +1,4 @@
+export interface World {
+    [key: string]: unknown;
+}
+export type WorldFactory<W extends World = World> = () => W;

package/dist/tests/assertions/config-assertions.test.d.ts

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

package/dist/tests/assertions/output-assertions.test.d.ts

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

package/dist/tests/cli/cli-runner.test.d.ts

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

package/dist/tests/features/self-test.steps.d.ts

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

package/dist/tests/features/self-test.test.d.ts

@@ -0,0 +1 @@
+import "./self-test.steps";

package/dist/tests/fixtures/sample-project/src/main.d.ts

@@ -0,0 +1 @@
+export declare function greet(name: string): string;

package/dist/tests/fixtures-manager/fixture-manager.test.d.ts

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

package/dist/tests/parser/adapter.test.d.ts

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

package/dist/tests/parser/models.test.d.ts

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

package/dist/tests/random/seeded-rng.test.d.ts

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

package/dist/tests/registry/expression-adapter.test.d.ts

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

package/dist/tests/registry/parameter-types.test.d.ts

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

package/dist/tests/registry/step-registry.test.d.ts

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

package/dist/tests/reporting/error-formatter.test.d.ts

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

package/dist/tests/reporting/pending-steps.test.d.ts

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

package/dist/tests/runner/feature-runner.test.d.ts

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

package/dist/tests/runner/hook-runner.test.d.ts

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

package/dist/tests/runner/scenario-runner.test.d.ts

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@questi0nm4rk/feats",
+  "version": "1.0.0",
+  "description": "BDD/Gherkin test framework for Bun — feature testing with typed step definitions",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/feats.ts",
+      "import": "./dist/feats.js",
+      "types": "./dist/src/feats.d.ts"
+    },
+    "./plugin": {
+      "bun": "./src/plugin/bun-plugin.ts",
+      "import": "./dist/plugin/bun-plugin.js",
+      "types": "./dist/src/plugin/bun-plugin.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "build": "bun build src/feats.ts src/plugin/bun-plugin.ts --outdir dist --target bun",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist"
+  },
+  "dependencies": {
+    "@cucumber/cucumber-expressions": "^19.0.0",
+    "@cucumber/gherkin": "^37.0.0",
+    "@cucumber/messages": "^32.0.0",
+    "smol-toml": "^1.5.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.8.0"
+  }
+}

package/src/assertions/config-assertions.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+
+export interface AssertConfigOpts {
+  readonly format?: "json" | "toml" | "yaml";
+  readonly subset?: boolean;
+}
+
+type ConfigFormat = "json" | "toml" | "yaml";
+
+function detectFormat(filePath: string): ConfigFormat {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".json") return "json";
+  if (ext === ".toml") return "toml";
+  if (ext === ".yaml" || ext === ".yml") return "yaml";
+  throw new Error(`Cannot auto-detect config format from extension: ${ext}`);
+}
+
+function parseConfig(content: string, format: ConfigFormat): unknown {
+  if (format === "json") return JSON.parse(content) as unknown;
+  if (format === "toml") return parseToml(content);
+  return parseYaml(content) as unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function diffValues(expected: unknown, actual: unknown, path: string, subset: boolean): string[] {
+  if (isRecord(expected) && isRecord(actual)) {
+    return diffObjects(expected, actual, path, subset);
+  }
+
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    return diffArrays(expected, actual, path, subset);
+  }
+
+  const expectedStr = JSON.stringify(expected);
+  const actualStr = JSON.stringify(actual);
+  if (actualStr !== expectedStr) {
+    return [`${path}: expected ${expectedStr}, got ${actualStr}`];
+  }
+  return [];
+}
+
+function diffArrays(
+  expected: unknown[],
+  actual: unknown[],
+  path: string,
+  subset: boolean,
+): string[] {
+  const errors: string[] = [];
+
+  if (!subset && expected.length !== actual.length) {
+    errors.push(`${path}: expected array length ${expected.length}, got ${actual.length}`);
+    return errors;
+  }
+
+  for (let i = 0; i < expected.length; i++) {
+    if (i >= actual.length) {
+      errors.push(`${path}[${i}]: expected ${JSON.stringify(expected[i])}, got undefined`);
+      continue;
+    }
+    errors.push(...diffValues(expected[i], actual[i], `${path}[${i}]`, subset));
+  }
+
+  return errors;
+}
+
+function diffObjects(
+  expected: Record<string, unknown>,
+  actual: unknown,
+  path: string,
+  subset: boolean,
+): string[] {
+  const errors: string[] = [];
+
+  if (!isRecord(actual)) {
+    errors.push(`${path}: expected object, got ${typeof actual}`);
+    return errors;
+  }
+
+  for (const [key, expectedVal] of Object.entries(expected)) {
+    const fullPath = path !== "" ? `${path}.${key}` : key;
+    const actualVal = actual[key];
+
+    if (actualVal === undefined) {
+      errors.push(`${fullPath}: expected ${JSON.stringify(expectedVal)}, got undefined`);
+      continue;
+    }
+
+    errors.push(...diffValues(expectedVal, actualVal, fullPath, subset));
+  }
+
+  if (!subset) {
+    for (const key of Object.keys(actual)) {
+      if (!(key in expected)) {
+        const fullPath = path !== "" ? `${path}.${key}` : key;
+        errors.push(`${fullPath}: unexpected key in actual`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+export function assertConfig(
+  filePath: string,
+  expected: Record<string, unknown>,
+  opts?: AssertConfigOpts,
+): void {
+  const subset = opts?.subset ?? true;
+  const format = opts?.format ?? detectFormat(filePath);
+  const content = readFileSync(filePath, "utf-8");
+  const actual = parseConfig(content, format);
+
+  const errors = diffObjects(expected, actual, "", subset);
+  if (errors.length > 0) {
+    throw new Error(`Config assertion failed:\n  ${errors.join("\n  ")}`);
+  }
+}

package/src/assertions/output-assertions.ts

@@ -0,0 +1,67 @@
+import type { CLIResult } from "@/cli/cli-result";
+
+export interface OutputExpectations {
+  readonly stdout?: string | RegExp;
+  readonly stderr?: string | RegExp;
+  readonly exitCode?: number;
+  readonly contains?: string;
+  readonly notContains?: string;
+}
+
+function matchesExpectation(actual: string, expected: string | RegExp): boolean {
+  if (typeof expected === "string") {
+    return actual.includes(expected);
+  }
+  return expected.test(actual);
+}
+
+function serializeExpected(expected: string | RegExp): string {
+  if (typeof expected === "string") {
+    return JSON.stringify(expected);
+  }
+  return expected.toString();
+}
+
+export function assertOutput(result: CLIResult, expectations: OutputExpectations): void {
+  if (expectations.stdout !== undefined) {
+    if (!matchesExpectation(result.stdout, expectations.stdout)) {
+      throw new Error(
+        `stdout assertion failed: expected ${serializeExpected(expectations.stdout)}, got ${JSON.stringify(result.stdout)}`,
+      );
+    }
+  }
+
+  if (expectations.stderr !== undefined) {
+    if (!matchesExpectation(result.stderr, expectations.stderr)) {
+      throw new Error(
+        `stderr assertion failed: expected ${serializeExpected(expectations.stderr)}, got ${JSON.stringify(result.stderr)}`,
+      );
+    }
+  }
+
+  if (expectations.exitCode !== undefined) {
+    if (result.exitCode !== expectations.exitCode) {
+      throw new Error(
+        `exitCode assertion failed: expected ${expectations.exitCode}, got ${result.exitCode}`,
+      );
+    }
+  }
+
+  const combined = result.stdout + result.stderr;
+
+  if (expectations.contains !== undefined) {
+    if (!combined.includes(expectations.contains)) {
+      throw new Error(
+        `contains assertion failed: expected output to contain ${JSON.stringify(expectations.contains)}`,
+      );
+    }
+  }
+
+  if (expectations.notContains !== undefined) {
+    if (combined.includes(expectations.notContains)) {
+      throw new Error(
+        `notContains assertion failed: expected output not to contain ${JSON.stringify(expectations.notContains)}`,
+      );
+    }
+  }
+}

package/src/cli/cli-result.ts

@@ -0,0 +1,6 @@
+export interface CLIResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  readonly timedOut: boolean;
+}

package/src/cli/cli-runner.ts

@@ -0,0 +1,66 @@
+import type { CLIResult } from "@/cli/cli-result";
+
+export interface RunCliOpts {
+  readonly cwd?: string;
+  readonly timeout?: number;
+  readonly env?: Record<string, string>;
+  readonly stdin?: string;
+}
+
+export async function runCli(
+  command: string,
+  args?: string[],
+  opts?: RunCliOpts,
+): Promise<CLIResult> {
+  const timeout = opts?.timeout ?? 30000;
+
+  const stdinValue: "ignore" | Uint8Array =
+    opts?.stdin !== undefined ? new TextEncoder().encode(opts.stdin) : "ignore";
+
+  const envValue = opts?.env !== undefined ? { ...process.env, ...opts.env } : process.env;
+
+  const spawnOpts = {
+    env: envValue,
+    stdin: stdinValue,
+    stdout: "pipe" as const,
+    stderr: "pipe" as const,
+    ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
+  };
+
+  const proc = Bun.spawn([command, ...(args ?? [])], spawnOpts);
+
+  let timedOut = false;
+
+  const waitWithTimeout = async (): Promise<number> => {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill();
+        resolve(1);
+      }, timeout);
+
+      proc.exited
+        .then((code) => {
+          clearTimeout(timer);
+          resolve(code ?? 1);
+        })
+        .catch(() => {
+          clearTimeout(timer);
+          resolve(1);
+        });
+    });
+  };
+
+  const [exitCode, stdoutText, stderrText] = await Promise.all([
+    waitWithTimeout(),
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+
+  return {
+    stdout: stdoutText,
+    stderr: stderrText,
+    exitCode,
+    timedOut,
+  };
+}

package/src/feats.ts

@@ -0,0 +1,30 @@
+// Assertions
+export { assertConfig } from "./assertions/config-assertions";
+export { assertOutput } from "./assertions/output-assertions";
+
+// CLI execution
+export type { CLIResult } from "./cli/cli-result";
+export { runCli } from "./cli/cli-runner";
+
+// Fixtures
+export { composeFixtures, setupFixture } from "./fixtures/fixture-manager";
+export type { FixtureProject } from "./fixtures/fixture-project";
+
+// Feature loading + running
+export { loadFeatures, parseFeature } from "./parser/adapter";
+export type { DataTable, Feature, ParsedStep, Scenario, Tag } from "./parser/models";
+
+// Random
+export type { SeededRng } from "./random/seeded-rng";
+export { createRng } from "./random/seeded-rng";
+
+// Step definitions
+export { defineParameterType } from "./registry/parameter-types";
+export { Given, Step, Then, When } from "./registry/step-registry";
+export type { RunOptions } from "./runner/feature-runner";
+export { runFeatures } from "./runner/feature-runner";
+// Lifecycle hooks
+export { After, Before } from "./runner/hook-runner";
+
+// Types
+export type { World, WorldFactory } from "./state/world";