@pikku/inspector 0.12.47 → 0.12.49

package/CHANGELOG.md

@@ -1,3 +1,221 @@
+## 0.12.49
+
+### Patch Changes
+
+- 426610a: Scenario instrumentation is no longer scaffolded into projects, and no longer deploys.
+
+  `scaffold.scenarios` generated four functions — `pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls` — into the project's own source. As project source they were indistinguishable from application code: registered in the app bootstrap, listed in the app's function and RPC meta, and shipped `expose: true` inside every deployed bundle. Coverage and stub inspection are things you do to a development server; production carried two endpoints that fingerprint the build and one that resets a global tracker, gated only by whether a metadata file happened to sit beside the bundle.
+
+  `pikku dev` now registers the implementations itself, after the app bootstrap. Nothing is generated, nothing is written to the project, and a bundle cannot carry what was never in its bootstrap — `pikku serve` and every deployed unit have no trace of them. The scenario runner reaches them over `/rpc/<name>` exactly as before.
+
+  Also:
+  - The inspector ignores these four names wherever it finds them, so a project that has not regenerated — and still has the scaffolded file checked in — stops deploying it immediately. Codegen deletes the retired scaffold on its next run.
+  - They no longer count towards a project's function total, so `pikku scenario --coverage` stops reporting four permanently-uncovered functions that were never the project's to cover.
+  - The instrumentation no longer carries schemas (there was nothing to validate but one optional string), which drops the `zod` dependency the scaffold silently required of every project that enabled it.
+  - They are registered sessionless, so `scaffold.scenarios: true` — as opposed to `'auth'` — now genuinely means "no session required". As a sessioned `pikkuFunc` with `auth: false`, it demanded a session anyway and logged a warning saying so.
+
+- 09973b9: Scenarios, features and steps no longer reach a deployment.
+
+  Steps were already held back from the app bootstrap, so a deployed server never imported a step body. Everything _about_ a scenario still travelled with the application: a `pikkuScenario(...)` is a function, so its name, schemas and hashes sat in the app function meta; the schemas it and its steps validate against sat in the app's `register.gen.ts` — on one project 458 of the 582 registered schemas belonged to tests; its name sat in the internal RPC meta; and because a scenario is _also_ a workflow, the inspector synthesised a `wf-orchestrator-<scenario>` queue worker for each one. The deploy analyzer, which reads inspector state rather than the partitioned codegen output, then read all of it back as application code: a unit per scenario, a `WorkflowDefinition` per scenario, and a real queue per scenario. A 13-scenario suite turned into 13 production queues named after tests, waiting for a provider to create them.
+
+  The existing scenario/app partition is now applied everywhere it was missing. `FunctionRuntimeMeta` gains a `scenario` marker (the counterpart of `scenarioStep`) so a scenario body is recognisable without walking the workflow graph; scenario bodies join their steps on the scenario side of the function-meta and registration split; schemas only a scenario or step needs are written and registered under `.pikku/scenarios/schemas/` and imported by the scenario bootstrap alone; scenario names are dropped from the internal RPC meta; no orchestrator queue worker is synthesised for a scenario; and the deploy analyzer drops both scenario functions and scenario workflows before it decides what a deployment contains.
+
+  The MCP metas are keyed by wiring rather than by function, so a scenario wired as an MCP tool, resource or prompt was the one id that still reached the manifest after the function and workflow filters — as an endpoint on the gateway plus a gateway dependency on a unit that was never emitted. Those ids are now filtered too.
+
+  `scenarioSchemaDirectory` is rejected when it resolves to the same directory as `schemaDirectory`. A schema write owns its directory — it emits `register.gen.ts` and prunes every schema file its own required-set does not name — so sharing one would replace the application register with the scenario-only one and delete the app's schema files, which nothing downstream can detect.
+
+  Nothing changes for `pikku scenario run` — the scenario bootstrap still registers every scenario, feature, step, meta and schema. What changes is that a bundle stops carrying them.
+
+- Updated dependencies [8a2c993]
+- Updated dependencies [a261006]
+- Updated dependencies [09973b9]
+  - @pikku/core@0.12.71
+
+## 0.12.48
+
+### Patch Changes
+
+- 04b8607: Make the unmodellable-for-of diagnostic tell you what is actually wrong. It always blamed the iterable ("its iterable must be a data array"), which was false whenever the real cause was a `workflow.do` nested inside an `if`/`switch` — a DSL fanout body is a flat list of steps with no branch member, so the diagnostic now says so and points at `.filter` or `pikkuWorkflowComplexFunc`. Also stops the same diagnostic firing on a `for-of` that contains no workflow call at all: a loop that only massages locals has no step to lose, so erroring on it was a false positive.
+- 7c8f015: Hard-error on a for-of a DSL workflow can't model, instead of silently dropping it.
+
+  A `pikkuWorkflowFunc` (DSL) whose body contained a computed/counting loop — e.g. `for (const i of [...Array(n).keys()])` — used to serialize with **zero steps**: the DSL extractor only models a for-of as a sequential fanout over a data-array identifier/field (`data.items`), so a non-path iterable made `extractSequentialFanout` return null and the extractor dropped the loop _and every `workflow.do` inside it_. The invoked functions then never entered `invokedFunctions`, so they got no `addFunction()` registration and threw `Function not found` at runtime — a silent codegen footgun that bricked every prod sandbox create.
+
+  Now the extractor pushes a validation error naming the offending for-of, so `pikkuWorkflowFunc` reports `INVALID_DSL_WORKFLOW` at codegen. A genuine control-flow/counting loop belongs in `pikkuWorkflowComplexFunc`, which falls back to the basic AST walk that _does_ register loop-invoked functions.
+
+- 5962e51: Give the inspector's program the project's tsconfig path mappings.
+
+  The inspector builds its own TypeScript program rather than reusing the project's, which is what keeps a cold run affordable — but it hand-rolled its compiler options and so had no `paths`. An import the project resolves only through a `paths` entry therefore did not resolve inside the inspector, and the factory the inspected function was passed to came back as `any`. A function whose input type comes from that factory's contextual type — rather than an explicit generic or a named `input:` schema — then recorded no input at all, silently, with no diagnostic.
+
+  `inspect` takes a new `tsconfig` option (the CLI passes `config.tsconfig`, including on a setup-only run, where `schemaConfig` is absent). Only resolution keys are copied across — `baseUrl`, `paths`, `rootDirs`, `pathsBasePath`. Type-inference options such as `strict` deliberately stay the inspector's own, because changing those would change the types it records.
+
+  This was latent rather than live: the generic path reads type _nodes_, the schema path reads an identifier, output types come from the handler body, and JSON schemas are generated by a separate tsconfig-aware program — so nothing in the tree reached the contextual-type fallback. Regenerating the e2e project and the `functions` template produces byte-identical output.
+
+- 5962e51: Add `pikkuFeature`, a grouping primitive for scenarios.
+
+  A feature groups scenarios the way gherkin's `Feature:` groups `Scenario:`, and gets `Examples:` for free as an ordinary loop:
+
+  ```ts
+  export const credentialFeature = pikkuFeature({
+    name: 'Credential API',
+    tags: ['credential'],
+    before: startsMockOAuthServer,
+    after: stopsMockOAuthServer,
+    scenarios: [
+      credentialLazyLoadScenario,
+      ...['stripe', 'google', 'hmac-key'].map((name) => ({
+        scenario: credentialRoundTripScenario,
+        data: { name },
+      })),
+    ],
+  })
+  ```
+
+  - Scenarios are referenced by **imported identifier**, not by string name, so a renamed or deleted scenario is a compile error rather than a silent skip. A `{ scenario, data }` entry's `data` is typed against that scenario's own input.
+  - Feature hooks run **once around the whole group** (`before → a → b → c → after`), not per scenario, and `after` runs in a `finally`. Per-scenario setup stays the scenario's own `before`; gherkin's `Background:` is deliberately not expressible.
+  - A scenario's effective tags are its own plus its feature's, so `--tags credential` selects through the feature.
+  - New `--features` selector on `pikku scenario run`, and `pikku scenario list` now prints features with their scenarios indented. Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs its hooks exactly once around those two.
+  - The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
+
+  `pikkuFeature` infers its scenario list with a `const` generic, so `CoreFeature['scenarios']` is `readonly` — otherwise the emitted `addFeature(id, feature)` call does not typecheck.
+
+  Membership is resolved at runtime by object identity — `pikkuScenario` returns its config verbatim, so a feature holds the very object that was registered. That is what lets the scenario list be built by a loop, which no static analysis could enumerate. It also means a scenario constructed inline inside a feature is never registered, and is reported as unresolved rather than silently running as something else.
+
+- 5962e51: Add `before` / `after` hooks to `pikkuScenario`, and make an unextractable scenario a hard error.
+
+  A scenario config now takes `before` and `after`. Both have the same signature as `func` — `(services, data, wire)` — with the return value discarded, so there is no new type to learn and a hook reaches the app the same way the body does, through `wire.actors`:
+
+  ```ts
+  export const credentialScenario = pikkuScenario({
+    title: 'A credential is loaded on first use',
+    tags: ['scenario', 'credential'],
+    before: resetsCredentials,
+    after: removesInstalledAddon,
+    func: async (services, data, { scenario, actors }) => { ... },
+  })
+  ```
+
+  - `before` throwing skips the body and fails the run, but `after` still runs.
+  - `after` always runs, in a `finally`. Throwing fails a run that would otherwise have passed; on an already-failed run it attaches as the `cause` and never replaces the original error.
+  - Neither runs when the run is suspended or waiting — teardown only fires at a terminal outcome.
+  - Hooks are not ladder rows: the runner records nothing for them, and a failure is labelled by phase via the new `ScenarioHookError`.
+  - Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs — a workflow is durable and resumable, so a callback that reran on every replay would have no honest meaning.
+
+  Two fixes that scenarios needed to be safe to write:
+  - A closure in a complex-workflow or scenario body is no longer held to the DSL statement whitelist. A single `try`/`catch` inside any callback previously failed extraction, and the fallback path understands `do`/`sleep` but not `step`/`given`/`when`/`then` — so the scenario registered with **zero steps** and passed vacuously, with no diagnostic. Plain DSL workflows still descend into callbacks, which is what validates fanout bodies.
+  - New `PKU679`: a scenario that fails DSL extraction is now a critical error and refuses to register, instead of silently registering empty. A scenario that declares no input parameter at all is legitimate and still extracts.
+
+- a436645: Redesign the console's scenarios screen as living documentation of a project's BDD features.
+
+  The inspector now statically extracts `pikkuFeature` declarations — name, description, tags, the scenarios each one groups (including `{ scenario, data }` examples), and whether it declares `before`/`after` — and the CLI writes them to `<outDir>/scenarios/features.gen.json`, which `MetaService.getFeaturesMeta()` reads and the console addon returns from `getAllMeta`.
+
+  The scenarios page reads that back as a document: features on the left, and on the right the selected feature's scenarios, each rendered as the given/when/then ladder of prose its author actually wrote, with repeats shown as `for each x in xs`, `Examples:` tables for parameterised entries, skip reasons stated rather than hidden, and each scenario's cast of personas inline. The Flows/Personas segmented control is gone; tags filter the document the same way `pikku scenario run --tags` filters a run.
+
+- 47478a4: Let a scenario declare why it is held out of a default run.
+
+  `pikkuScenario({ skip: 'why' })` keeps the scenario in the plan and reports it as `SKIP <name> (<reason>)` on the ladder, instead of the alternatives available until now: deleting it, commenting it out, or leaving it red. Naming it directly with `--flows` clears the quarantine and runs it; selecting the feature it belongs to does not, because a feature is a group and running the group should not silently drag a quarantined member in.
+
+  The run report's `skipped` list now carries a reason per scenario rather than assuming `--no-browser`, so a browser scenario held back on a machine with no browser reads differently from one the project quarantined itself.
+
+  `@pikku/console` gains a test id on the addon detail page's Setup tab, which was previously only reachable through its translated label.
+
+- 2434f1b: Fix two silent losses in scenario step extraction.
+
+  Destructuring a scenario step result (`const { threadId } = await scenario.given(...)`) dropped the
+  step from the graph without a diagnostic — the step stayed fully typed and present in the step map,
+  then failed at runtime with `Function not found`. It now reports PKU679, like every other step form
+  the DSL cannot model.
+
+  A constant referenced as step input (`{ resourceId: RESOURCE_ID }`) was serialized as
+  `{ $ref: 'trigger', path: 'RESOURCE_ID' }` — a read of a trigger field that does not exist. A `const`
+  with a literal initializer is now inlined as that literal.
+
+- 5962e51: Add `template` to `pikkuScenarioStep`, so a step's reported prose names the values it was called with.
+
+  `description` documents what a step does, for the console and for whoever reads the source. `template` is what a reader of the report sees, with `{placeholders}` filled from the input the step was actually called with:
+
+  ```ts
+  export const seesAddonCard = pikkuScenarioStep<
+    { packageName: string; state?: 'installed' | 'available' },
+    { visible: true },
+    true
+  >({
+    name: 'seesAddonCard',
+    description: 'sees an addon in the gallery',
+    template: 'sees {state} addon {packageName}',
+    browser: true,
+    func: async (_services, { packageName, state }, { browser }) => { … },
+  })
+  ```
+
+  ```
+  Then  the admin sees at least 10 addons on offer          ✓  3ms
+  When  the admin searches for stripe                       ✓  10ms
+  Then  the admin sees available addon @pikku/addon-stripe  ✓  77ms
+  ```
+
+  Previously the only way to get that was a `description` at every call site, which meant writing the sentence once per call rather than once per step — and a call site that forgot it reported the same sentence three times in a row.
+  - A placeholder with no recorded value renders as nothing and the surrounding whitespace collapses, so an omitted optional input reads as a shorter sentence rather than leaking a literal `{state}` into the report. Type placeholder values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`).
+  - A call-site `description` still wins, the same way it already won over the step's `description`.
+  - `renderStepTemplate` is exported from `@pikku/core/workflow` alongside `composeStepProse`, so the CLI reporter and the console render identically.
+
+  Scenario steps now record their input on the run (`inlineStep` persisted `null` for every inline step, so there was nothing for a reporter to interpolate). This is what `getRunSteps` already exposes as `data` for RPC steps.
+
+  A step called from a loop gets its template too. Its durable name is built at runtime (`sees @pikku/addon-todos`) from a declaration the static meta records verbatim (`sees ${packageName}`), so the two can never match by name — it used to fall back to the bare name, with no keyword, actor or template:
+
+  ```
+          sees @pikku/addon-console                              ✓  85ms
+  Then    the admin sees installed addon @pikku/addon-console    ✓  92ms
+  ```
+
+  The join is by **step function**. A scenario step is dispatched by name exactly as an RPC is, so it now records that name in the run's existing `rpcName` slot — no new field, no schema change in any workflow store. Nothing dispatches off that value anywhere; step identity always comes from the code being replayed.
+
+  To keep the slot honest, a scenario step is now its own **kind of RPC**, alongside public / private / remote: `FunctionMeta.scenarioStep` marks it, and `rpcExposed` refuses it even if something marks it `expose: true`. Steps were already left out of the RPC registry; this makes "never network-callable" a property the runtime enforces rather than one the registration path happens to produce.
+
+  `collectScenarioStepProse` now returns `{ byStepName, byStepFunc }` rather than a bare `Map`, and `buildStepLadder` takes that. The step name still wins; the function index only decides steps recorded under a name no declaration carries, and a function called from several sites that disagree on their prose is left out rather than guessed at.
+
+- 5962e51: Add `pikkuScenarioStep` — named, typed scenario steps whose body is an ordinary pikku function.
+
+  A scenario step is referenced by typed string name, the same way `workflow.do` references an RPC, and is checked against a generated `FlattenedScenarioStepMap`:
+
+  ```ts
+  export const buysAnApple = pikkuScenarioStep({
+    name: 'buysAnApple',
+    description: 'buys an apple',
+    func: async (services, data: { qty: number }) => { ... },
+  })
+
+  await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })
+  // renders: Given the shopper buys an apple
+  ```
+
+  - `given`/`when`/`then` are sugar over `step`, setting only the prose prefix. The runner renders a step ladder from the recorded run.
+  - Steps default to `retries: 0` — a failed assertion is not retried.
+  - Steps are deliberately **not** registered as RPCs, so a browser-driving step is never network-callable.
+  - `browser: true` steps receive a browser handle on the wire. `@pikku/playwright` is a new package providing the Playwright-backed provider, signing each actor's browser context in through the same actor path the HTTP actors use. Without a provider, `pikku scenario run --no-browser` **skips** browser scenarios instead of failing them.
+  - New diagnostics: PKU677 (a `browser: true` step called without an actor) and PKU678 (a step target that is not a static string literal).
+  - Fixes `--no-<flag>` boolean negation in the CLI command parser, which previously parsed as an unknown option.
+  - Fixes PKU673 (a scenario func destructuring services), which never fired because it ran before function meta existed; it now runs in post-processing.
+  - Fixes scenario/workflow steps nested in `for...of` and `Promise.all` being dropped from workflow meta.
+
+- Updated dependencies [539ee0b]
+- Updated dependencies [a1a6816]
+- Updated dependencies [dc3e11e]
+- Updated dependencies [24da616]
+- Updated dependencies [04bfe3f]
+- Updated dependencies [5962e51]
+- Updated dependencies [5962e51]
+- Updated dependencies [cd6453c]
+- Updated dependencies [a436645]
+- Updated dependencies [46cf63e]
+- Updated dependencies [9e666bc]
+- Updated dependencies [1c841d8]
+- Updated dependencies [47478a4]
+- Updated dependencies [9e666bc]
+- Updated dependencies [5962e51]
+- Updated dependencies [5962e51]
+- Updated dependencies [61b9bf8]
+  - @pikku/core@0.12.70
+
 ## 0.12.47
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,106 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Yasser Fadl and Pikku contributors
+Licensed Work:        TypeScript inspector for Pikku — discovers functions and wirings to drive code generation (@pikku/inspector)
+                      Pikku Console (@pikku/console)
+                      The Licensed Work is (c) 2021 - present Yasser Fadl and Pikku contributors
+Additional Use Grant: You may make production use of the Licensed Work for any purpose,
+                      including creating free or open source software. However, you may
+                      not offer as a commercial product or service any software featuring
+                      a visual or graphical interface for authoring, editing, building,
+                      or managing Pikku code, Pikku functions, Pikku handlers, or Pikku
+                      workflows.
+Change Date:          Four years from the date the Licensed Work was first made available
+Change License:       MIT License
+
+For information about alternative licensing arrangements, contact yasser.fadl@gmail.com
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open Source
+license. However, the Licensed Work will eventually be made available under an Open
+Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works,
+redistribute, and make non-production use of the Licensed Work. The Licensor may make
+an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this License,
+whichever comes first, the Licensor hereby grants you rights under the terms of the
+Change License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in
+effect as described in this License, you must purchase a commercial license from the
+Licensor, its affiliated entities, or authorized resellers, or you must refrain from
+using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the
+Licensed Work, are subject to this License. This License applies separately for each
+version of the Licensed Work and the Change Date may vary for each version of the
+Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of the
+Licensed Work. If you receive the Licensed Work in original or modified form from a
+third party, the terms and conditions set forth in this License apply to your use of
+that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate
+your rights under this License for the current and all other versions of the Licensed
+Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or its
+affiliates (provided that you may use a trademark or logo of Licensor as expressly
+required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS"
+BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED,
+INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your works,
+and to refer to it using the trademark "Business Source License", as long as you
+comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or a
+   license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be included
+   in a program with software provided under GPL Version 2.0 or a later version.
+   Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not impose
+   any additional restriction on the right granted in this License, as the Additional
+   Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Note: Every other Pikku package — @pikku/core, the runtimes, the services, the clients,
+and @pikku/skills — is licensed under the MIT License. Each package ships its own LICENSE
+file stating its terms; that file governs, and this one covers only the Licensed Work
+named above.
+
+In particular, the Pikku agent skills (@pikku/skills) are MIT. They are the instruction
+set coding agents read to build, wire and deploy Pikku projects, and they are meant to be
+adopted, forked and extended by any harness — so their terms do not depend on the CLI
+that happens to install them.

package/README.md

@@ -1,3 +1,29 @@
-# Pikku CLI
+# @pikku/inspector
 
-This package is part of @pikku/mono and is responsible for all the intropsection and file generations.
+The TypeScript inspector behind the Pikku CLI. Walks your source with the
+TypeScript compiler API to discover functions, wirings and their types, and
+produces the state the CLI generates code from.
+
+Most users get this transitively via `@pikku/cli`; install it directly only if
+you are building your own tooling on top of Pikku's introspection.
+
+## Install
+
+```bash
+npm install @pikku/inspector
+```
+
+## Usage
+
+```typescript
+import { inspect, getInitialInspectorState } from '@pikku/inspector'
+
+const state = getInitialInspectorState()
+await inspect(['src'], tsconfigPath, state)
+```
+
+Diagnostics come back as `CodedDiagnostic` values with a stable `ErrorCode`.
+
+## Docs
+
+https://pikku.dev/docs

package/dist/add/add-feature.d.ts

@@ -0,0 +1,19 @@
+import type { AddWiring } from '../types.js';
+/**
+ * Inspector for `pikkuFeature()` calls.
+ *
+ * A feature is the document structure the console renders — its name,
+ * description, tags and the order of its scenarios are what a reader sees — so
+ * everything the config states literally is extracted here.
+ *
+ * What cannot be extracted is a scenarios entry that is not literal:
+ * `...['stripe', 'google'].map((name) => ({ scenario, data: { name } }))` is
+ * ordinary TypeScript, and no AST walk can enumerate it. Those entries are
+ * counted in `unresolvedEntries` rather than dropped, and membership for them
+ * is resolved at runtime by object identity (`resolveFeatureScenarios`), where
+ * the array has actually been evaluated.
+ *
+ * The export location is recorded either way, which is what the CLI needs to
+ * emit its `addFeature(...)` wiring line.
+ */
+export declare const addFeature: AddWiring;

package/dist/add/add-feature.js

@@ -0,0 +1,200 @@
+import * as ts from 'typescript';
+import { extractFunctionName } from '../utils/extract-function-name.js';
+import { ErrorCode } from '../error-codes.js';
+/**
+ * Reads a fully literal expression into a plain value.
+ *
+ * Used for a `{ scenario, data }` entry's `data`, which is gherkin's
+ * `Examples:` row. Anything not literal yields `undefined` — a computed row
+ * belongs to the runtime-resolved portion, not to the extracted meta.
+ */
+const literalValue = (node) => {
+    if (ts.isStringLiteralLike(node)) {
+        return node.text;
+    }
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (node.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (node.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    if (node.kind === ts.SyntaxKind.NullKeyword) {
+        return null;
+    }
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)) {
+        return -Number(node.operand.text);
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+        const values = [];
+        for (const element of node.elements) {
+            const value = literalValue(element);
+            if (value === undefined) {
+                return undefined;
+            }
+            values.push(value);
+        }
+        return values;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+        const value = {};
+        for (const property of node.properties) {
+            if (!ts.isPropertyAssignment(property)) {
+                return undefined;
+            }
+            const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)
+                ? property.name.text
+                : undefined;
+            if (key === undefined) {
+                return undefined;
+            }
+            const propertyValue = literalValue(property.initializer);
+            if (propertyValue === undefined) {
+                return undefined;
+            }
+            value[key] = propertyValue;
+        }
+        return value;
+    }
+    return undefined;
+};
+/**
+ * Resolves a scenario reference to the name it is declared under, following an
+ * import alias back to the original export so `{ x as y }` records `x`.
+ */
+const scenarioName = (node, checker) => {
+    if (!ts.isIdentifier(node)) {
+        return undefined;
+    }
+    const symbol = checker.getSymbolAtLocation(node);
+    if (!symbol) {
+        return node.text;
+    }
+    const resolved = symbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    return resolved.getName() || node.text;
+};
+const getProperty = (config, name) => {
+    const property = config.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === name);
+    return property && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : undefined;
+};
+const hasProperty = (config, name) => config.properties.some((p) => (ts.isPropertyAssignment(p) ||
+    ts.isMethodDeclaration(p) ||
+    ts.isShorthandPropertyAssignment(p)) &&
+    ts.isIdentifier(p.name) &&
+    p.name.text === name);
+const stringProperty = (config, name) => {
+    const value = getProperty(config, name);
+    return value && ts.isStringLiteralLike(value) ? value.text : undefined;
+};
+const stringArrayProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value || !ts.isArrayLiteralExpression(value)) {
+        return undefined;
+    }
+    const values = value.elements
+        .filter(ts.isStringLiteralLike)
+        .map((e) => e.text);
+    return values.length === value.elements.length ? values : undefined;
+};
+const readEntry = (element, checker) => {
+    if (ts.isIdentifier(element)) {
+        const scenario = scenarioName(element, checker);
+        return scenario ? { scenario } : undefined;
+    }
+    if (ts.isObjectLiteralExpression(element)) {
+        const reference = getProperty(element, 'scenario');
+        if (!reference) {
+            return undefined;
+        }
+        const scenario = scenarioName(reference, checker);
+        if (!scenario) {
+            return undefined;
+        }
+        const dataNode = getProperty(element, 'data');
+        if (!dataNode) {
+            return { scenario };
+        }
+        const data = literalValue(dataNode);
+        return data === undefined ? undefined : { scenario, data };
+    }
+    return undefined;
+};
+/**
+ * Inspector for `pikkuFeature()` calls.
+ *
+ * A feature is the document structure the console renders — its name,
+ * description, tags and the order of its scenarios are what a reader sees — so
+ * everything the config states literally is extracted here.
+ *
+ * What cannot be extracted is a scenarios entry that is not literal:
+ * `...['stripe', 'google'].map((name) => ({ scenario, data: { name } }))` is
+ * ordinary TypeScript, and no AST walk can enumerate it. Those entries are
+ * counted in `unresolvedEntries` rather than dropped, and membership for them
+ * is resolved at runtime by object identity (`resolveFeatureScenarios`), where
+ * the array has actually been evaluated.
+ *
+ * The export location is recorded either way, which is what the CLI needs to
+ * emit its `addFeature(...)` wiring line.
+ */
+export const addFeature = (logger, node, checker, state) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuFeature') {
+        return;
+    }
+    const { exportedName } = extractFunctionName(node, checker, state.rootDir);
+    if (!exportedName) {
+        logger.critical(ErrorCode.MISSING_NAME, `A pikkuFeature() must be assigned to an export — the export identifier is the feature's id.`);
+        return;
+    }
+    const feature = {
+        path: node.getSourceFile().fileName,
+        exportedName,
+        entries: [],
+        unresolvedEntries: 0,
+        hasBefore: false,
+        hasAfter: false,
+    };
+    const [config] = node.arguments;
+    if (config && ts.isObjectLiteralExpression(config)) {
+        const name = stringProperty(config, 'name');
+        const description = stringProperty(config, 'description');
+        const tags = stringArrayProperty(config, 'tags');
+        if (name !== undefined) {
+            feature.name = name;
+        }
+        if (description !== undefined) {
+            feature.description = description;
+        }
+        if (tags !== undefined) {
+            feature.tags = tags;
+        }
+        feature.hasBefore = hasProperty(config, 'before');
+        feature.hasAfter = hasProperty(config, 'after');
+        const scenarios = getProperty(config, 'scenarios');
+        if (scenarios && ts.isArrayLiteralExpression(scenarios)) {
+            for (const element of scenarios.elements) {
+                const entry = readEntry(element, checker);
+                if (entry) {
+                    feature.entries.push(entry);
+                }
+                else {
+                    feature.unresolvedEntries += 1;
+                }
+            }
+        }
+    }
+    state.workflows.featureFiles.set(exportedName, feature);
+};