@pikku/core 0.12.69 → 0.12.70

package/src/wirings/workflow/workflow.types.ts

@@ -1,5 +1,8 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
+} from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
 // Re-export WorkflowService from services module
@@ -38,12 +41,23 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
   PikkuScenarioWire,
 } from './dsl/workflow-dsl.types.js'
 
+// Re-export scenario step types
+export type {
+  ScenarioStepPhase,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  PikkuBrowserWire,
+  ScenarioBrowserProvider,
+} from './scenario-step.types.js'
+
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
 export interface WorkflowRunWire {
@@ -329,6 +343,82 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
+/**
+ * A scenario as a feature references it: either the scenario itself, or the
+ * scenario paired with the input to run it with. The paired form is gherkin's
+ * `Examples:` — the same scenario run once per row, written as an ordinary
+ * loop rather than a table.
+ */
+export type CoreFeatureScenario =
+  | CorePikkuFunctionConfig<any, any, any>
+  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
+
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * Hooks run **once around the whole group** (`before → a → b → c → after`),
+ * not per scenario — per-scenario setup is the scenario's own `before`. That
+ * is the one thing a feature deliberately cannot express: gherkin's
+ * `Background:` runs per scenario.
+ */
+export type CoreFeature = {
+  /** Human-readable name. The export identifier is the id. */
+  name: string
+  description?: string
+  tags?: string[]
+  /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
+  scenarios: readonly CoreFeatureScenario[]
+  before?: CorePikkuFunctionHook
+  after?: CorePikkuFunctionHook
+}
+
+/** One entry of a feature's scenario list, as extracted from the source. */
+export type FeatureMetaEntry = {
+  /** The scenario's declared export name — its key in `WorkflowsMeta`. */
+  scenario: string
+  /** The input this entry runs the scenario with — gherkin's `Examples:`. */
+  data?: unknown
+}
+
+/**
+ * A feature as the console reads it: the document structure around a group of
+ * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
+ * nothing app-facing has to import the scenario bootstrap to describe one.
+ */
+export type FeatureMeta = {
+  /** The export identifier. */
+  id: string
+  name: string
+  description?: string
+  tags: string[]
+  /** In declared order — a feature's reading order is its declaration order. */
+  entries: FeatureMetaEntry[]
+  /**
+   * Entries that could not be read statically (a spread, a `.map()`). Their
+   * membership is only known once the scenario bootstrap has been evaluated,
+   * so a non-zero count means this listing is partial.
+   */
+  unresolvedEntries: number
+  /** Hooks are runtime-only; only their presence is knowable from meta. */
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
+export type FeaturesMeta = Record<string, FeatureMeta>
+
+/** One planned scenario run, resolved from a feature's scenario list. */
+export type FeaturePlanEntry = {
+  featureId: string
+  featureName: string
+  scenarioName: string
+  /** The input this entry runs the scenario with, if the feature supplied one. */
+  data?: unknown
+  /** The scenario's own tags unioned with the containing feature's. */
+  tags: string[]
+}
+
 /**
  * Workflow client interface
  */
@@ -371,6 +461,13 @@ export type WorkflowsMeta = Record<
     expose?: boolean
     /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean
+    /**
+     * Why a scenario is held out of a default run. Stating the reason in code
+     * keeps the quarantine next to the scenario it applies to, rather than in
+     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
+     * regardless.
+     */
+    skip?: string
     /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[]
   }