@kraken-e2e/gherkin 0.1.0

package/dist/registry.js

@@ -0,0 +1,114 @@
+import { CucumberExpression, ParameterType, } from '@cucumber/cucumber-expressions';
+import { KrakenError } from '@kraken-e2e/contracts';
+import { createParameterTypeRegistry } from './parameter-types.js';
+/** Ordered parameter names in an expression source ('{actor} sees {string}'). */
+function parameterNames(source) {
+    return [...source.matchAll(/\{(\w+)\}/g)].map((match) => match[1] ?? '');
+}
+/** Survives duplicate copies of this package in one process (jiti + node_modules). */
+export const STEP_REGISTRY_BRAND = Symbol.for('kraken.stepRegistry/v1');
+export function isStepRegistry(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[STEP_REGISTRY_BRAND] === true);
+}
+export class StepRegistry {
+    [STEP_REGISTRY_BRAND] = true;
+    #definitions = [];
+    #parameterTypes;
+    constructor() {
+        this.#parameterTypes = createParameterTypeRegistry();
+    }
+    define(expressionSource, options, handler, kind = 'step') {
+        const names = parameterNames(expressionSource);
+        const actorParameterIndex = names.indexOf('actor');
+        if (actorParameterIndex === -1) {
+            throw new KrakenError('KRK-STEP-UNKNOWN-ACTOR', `Step "${expressionSource}" has no {actor} parameter. Every Kraken step is addressed ` +
+                'to exactly one actor (ADR-0004 D1).', { fix: "Start the expression with '{actor} …'." });
+        }
+        const expression = new CucumberExpression(expressionSource, this.#parameterTypes);
+        this.#definitions.push({
+            expressionSource,
+            expression,
+            options,
+            kind,
+            handler,
+            actorParameterIndex,
+        });
+    }
+    defineParameterType(options) {
+        this.#parameterTypes.defineParameterType(new ParameterType(options.name, options.regexp, null, options.transformer ?? ((value) => value), false, false));
+    }
+    get definitions() {
+        return this.#definitions;
+    }
+    /**
+     * Matches a pickle step's text. Zero matches → undefined (the compiler turns
+     * it into a STEP_UNMATCHED diagnostic); more than one → STEP_AMBIGUOUS error.
+     */
+    match(text) {
+        const matches = [];
+        for (const definition of this.#definitions) {
+            const matched = definition.expression.match(text);
+            if (!matched)
+                continue;
+            const values = matched.map((argument) => argument.getValue(null));
+            const actorName = String(values[definition.actorParameterIndex]);
+            const args = values.filter((_, index) => index !== definition.actorParameterIndex);
+            matches.push({ definition, actorName, args });
+        }
+        if (matches.length === 0)
+            return undefined;
+        if (matches.length > 1) {
+            throw new KrakenError('KRK-STEP-AMBIGUOUS', `Step "${text}" matches ${matches.length} definitions: ` +
+                matches.map((match) => `"${match.definition.expressionSource}"`).join(', '), { fix: 'Make the step expressions mutually exclusive.' });
+        }
+        return matches[0];
+    }
+}
+/**
+ * The step-authoring API (ADR-0004 D1). Instance-based — no import-order
+ * magic; destructure so call sites are bare identifiers, which is exactly what
+ * the Cucumber VS Code extension's tree-sitter queries recognize (appendix B):
+ *
+ *   export const { Given, When, Then } = createStepRegistry();
+ */
+export function createStepRegistry() {
+    const registry = new StepRegistry();
+    registerBuiltInSteps(registry);
+    const makeKeyword = () => (expression, optionsOrHandler, maybeHandler) => {
+        const options = typeof optionsOrHandler === 'function' ? {} : optionsOrHandler;
+        const handler = typeof optionsOrHandler === 'function' ? optionsOrHandler : maybeHandler;
+        if (!handler) {
+            throw new KrakenError('KRK-STEP-UNMATCHED', `Step "${expression}" has no handler.`);
+        }
+        registry.define(expression, options, handler, options.detached ? 'detach' : 'step');
+    };
+    return {
+        Given: makeKeyword(),
+        When: makeKeyword(),
+        Then: makeKeyword(),
+        defineParameterType: (options) => registry.defineParameterType(options),
+        registry,
+    };
+}
+/**
+ * Built-in choreography vocabulary (ADR-0004 D4) — deliberately minimal:
+ * signal waiting (v2 continuity) and background-task joining. App-domain
+ * steps belong to the USER's project, never here.
+ */
+export function registerBuiltInSteps(registry) {
+    registry.define('{actor} waits for the signal {string} within {duration}', {}, async (ctx, ...args) => {
+        const [name, timeoutMs] = args;
+        await ctx.actor.signals.waitFor(name, { timeoutMs });
+    }, 'wait-signal');
+    registry.define('{actor} waits for the signal {string} from {actor} within {duration}', {}, async (ctx, ...args) => {
+        const [name, from, timeoutMs] = args;
+        await ctx.actor.signals.waitFor(name, { timeoutMs, from });
+    }, 'wait-signal');
+    registry.define("{actor}'s background task {string} completes within {duration}", {}, async () => {
+        // The scheduler performs the join (compiler emits a 'join' node);
+        // this handler never runs.
+    }, 'join');
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kraken-e2e/gherkin",
+  "version": "0.1.0",
+  "description": "BDD front-end: .feature parsing (official Gherkin stack), typed step registry, scenario compiler, built-in choreography steps",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@cucumber/cucumber-expressions": "^20.0.0",
+    "@cucumber/gherkin": "^41.0.0",
+    "@cucumber/messages": "^33.0.4",
+    "@cucumber/tag-expressions": "^10.0.0",
+    "@kraken-e2e/contracts": "0.1.0",
+    "@kraken-e2e/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "license": "GPL-3.0-only",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}