@pikku/core 0.12.52 → 0.12.54

package/src/services/v8-coverage-service.ts

@@ -0,0 +1,165 @@
+// node:inspector is imported lazily inside start() so this module stays
+// loadable on runtimes without it (e.g. Cloudflare Workers).
+
+export interface CoverageRange {
+  startOffset: number
+  endOffset: number
+  count: number
+}
+
+export interface FunctionCoverage {
+  functionName: string
+  isBlockCoverage: boolean
+  ranges: CoverageRange[]
+}
+
+export interface ScriptCoverage {
+  scriptId: string
+  url: string
+  functions: FunctionCoverage[]
+}
+
+export type LineHits = Map<string, Map<number, number>>
+
+export type CoverageSnapshot =
+  | {
+      kind: 'v8-scripts'
+      scripts: ScriptCoverage[]
+      getScriptSource: (scriptId: string) => Promise<string>
+    }
+  | { kind: 'line-hits'; lineHits: LineHits }
+
+export type CoverageStatus = 'covered' | 'partial' | 'uncovered' | 'unknown'
+
+export interface FunctionCoverageEntry {
+  name: string
+  sourceFile: string
+  exposed: boolean
+  description: string | null
+  coveredLines: number
+  totalLines: number
+  missedLines: number[]
+  ratio: number
+  status: CoverageStatus
+}
+
+export interface FunctionCoverageReport {
+  generatedAt: string
+  summary: {
+    total: number
+    covered: number
+    partial: number
+    uncovered: number
+    unknown: number
+    overallRatio: number
+  }
+  functions: FunctionCoverageEntry[]
+}
+
+export interface CoverageFunctionMeta {
+  name: string
+  sourceFile: string
+  bodySourceFile?: string
+  exportedName?: string
+  expose?: boolean
+  description?: string | null
+  bodyStart?: number
+  bodyEnd?: number
+}
+
+export interface CoverageService {
+  start(): Promise<void>
+  takeCoverage(): Promise<CoverageSnapshot>
+  /** Maps the current snapshot onto function body spans. Provided by the
+   *  process that booted the coverage backend (the pikku CLI) — absent when
+   *  the runtime only exposes raw snapshots. */
+  takeReport?(
+    functionsMeta: Record<string, CoverageFunctionMeta>
+  ): Promise<FunctionCoverageReport>
+  reset(): Promise<void>
+  stop(): Promise<void>
+}
+
+type InspectorSession = {
+  connect(): void
+  disconnect(): void
+  post(
+    method: string,
+    params?: unknown,
+    callback?: (err: Error | null, result?: any) => void
+  ): void
+}
+
+export class V8CoverageService implements CoverageService {
+  private session: InspectorSession | null = null
+  private startPromise: Promise<void> | null = null
+
+  private post<T>(method: string, params?: unknown): Promise<T> {
+    const session = this.session
+    if (!session) {
+      throw new Error('V8CoverageService not started — call start() first')
+    }
+    return new Promise<T>((resolve, reject) => {
+      session.post(method, params, (err, result) =>
+        err ? reject(err) : resolve(result as T)
+      )
+    })
+  }
+
+  start(): Promise<void> {
+    this.startPromise ??= this.doStart()
+    return this.startPromise
+  }
+
+  private async doStart(): Promise<void> {
+    const inspector = await import('node:inspector')
+    this.session = new inspector.Session() as unknown as InspectorSession
+    this.session.connect()
+    await this.post('Profiler.enable')
+    await this.post('Debugger.enable')
+    await this.post('Profiler.startPreciseCoverage', {
+      callCount: true,
+      detailed: true,
+    })
+  }
+
+  async takeCoverage(): Promise<CoverageSnapshot> {
+    const { result } = await this.post<{ result: ScriptCoverage[] }>(
+      'Profiler.takePreciseCoverage'
+    )
+    return {
+      kind: 'v8-scripts',
+      scripts: result.filter((script) => script.url.startsWith('file://')),
+      getScriptSource: (scriptId) => this.getScriptSource(scriptId),
+    }
+  }
+
+  async getScriptSource(scriptId: string): Promise<string> {
+    const { scriptSource } = await this.post<{ scriptSource: string }>(
+      'Debugger.getScriptSource',
+      { scriptId }
+    )
+    return scriptSource
+  }
+
+  async reset(): Promise<void> {
+    await this.post('Profiler.stopPreciseCoverage')
+    await this.post('Profiler.startPreciseCoverage', {
+      callCount: true,
+      detailed: true,
+    })
+  }
+
+  async stop(): Promise<void> {
+    if (!this.session) return
+    try {
+      await this.post('Profiler.stopPreciseCoverage')
+      await this.post('Profiler.disable')
+      await this.post('Debugger.disable')
+    } finally {
+      this.session.disconnect()
+      this.session = null
+      this.startPromise = null
+    }
+  }
+}

package/src/types/core.types.ts

@@ -38,6 +38,7 @@ import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
 import type { MetaService } from '../services/meta-service.js'
+import type { CoverageService } from '../services/v8-coverage-service.js'
 import type { SessionStore } from '../services/session-store.js'
 import type {
   AuditDurability,
@@ -150,6 +151,12 @@ export type FunctionMeta = FunctionRuntimeMeta &
       isDirectFunction: boolean
       sourceFile: string
       exportedName: string
+      /** File containing the handler body when it differs from sourceFile (imported handlers) */
+      bodySourceFile?: string
+      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+      bodyStart: number
+      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+      bodyEnd: number
     } & CommonWireMeta
   >
 
@@ -293,6 +300,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   emailService?: EmailService
   /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
   metaService?: MetaService
+  /** V8 precise-coverage collector (`pikku dev --coverage` only) */
+  coverageService?: CoverageService
   /** Audit service for durable or staged audit event capture */
   audit?: AuditService
   /**

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

@@ -37,6 +37,20 @@ export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
   interval?: string | number
 }
 
+/** Options for workflow.expectError() */
+export interface WorkflowExpectErrorOptions extends WorkflowStepOptions {
+  /** Assert the error message matches (string = substring match). */
+  matches?: string | RegExp
+}
+
+/** Options for workflow.expectService() */
+export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
+  /** Assert a recorded call's first argument deep-equals this value. */
+  calledWith?: unknown
+  /** Assert the exact number of matching calls. Default: at least one. */
+  times?: number
+}
+
 /**
  * Type signature for workflow.do() RPC form - used by inspector
  */
@@ -381,6 +395,21 @@ export interface PikkuWorkflowWire {
     options?: WorkflowExpectEventuallyOptions
   ) => Promise<TOutput>
 
+  /** Error-path step (scenarios): succeeds only when the RPC throws; returns the message */
+  expectError: <TInput = any>(
+    stepName: string,
+    rpcName: string,
+    data: TInput,
+    options?: WorkflowExpectErrorOptions
+  ) => Promise<string>
+
+  /** Stub-assertion step (scenarios): asserts `service.method` was called on the target server */
+  expectService: (
+    stepName: string,
+    serviceMethod: string,
+    options?: WorkflowExpectServiceOptions
+  ) => Promise<void>
+
   /** Sleep for a duration */
   sleep: WorkflowWireSleep
 

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -60,6 +60,8 @@ import type {
   WorkflowServiceConfig,
   WorkflowStepOptions,
   WorkflowExpectEventuallyOptions,
+  WorkflowExpectErrorOptions,
+  WorkflowExpectServiceOptions,
 } from './workflow.types.js'
 import {
   continueGraph,
@@ -1099,12 +1101,6 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     })
   }
 
-  /**
-   * Start a new workflow run
-   * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
-   * @param options.inline - If true, execute workflow directly without queue service
-   * @param options.startNode - Starting node ID for graph workflows (from wire config)
-   */
   /**
    * Start a new workflow run
    * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -2229,6 +2225,104 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         )
       },
 
+      expectError: async (
+        stepName: string,
+        rpcName: string,
+        data: any,
+        options?: WorkflowExpectErrorOptions
+      ) => {
+        this.verifyStepName(stepName)
+        const resolvedRpcName =
+          addonNamespace && !rpcName.includes(':')
+            ? `${addonNamespace}:${rpcName}`
+            : rpcName
+        return await this.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            let result: any
+            try {
+              result = options?.actor
+                ? await options.actor.invoke(resolvedRpcName, data)
+                : await rpcService.rpcWithWire(resolvedRpcName, data, {})
+            } catch (e: any) {
+              const message = e?.message ?? String(e)
+              if (options?.matches) {
+                const matched =
+                  typeof options.matches === 'string'
+                    ? message.includes(options.matches)
+                    : options.matches.test(message)
+                if (!matched) {
+                  throw new Error(
+                    `[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`
+                  )
+                }
+              }
+              return message
+            }
+            throw new Error(
+              `[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`
+            )
+          },
+          options
+        )
+      },
+
+      expectService: async (
+        stepName: string,
+        serviceMethod: string,
+        options?: WorkflowExpectServiceOptions
+      ) => {
+        this.verifyStepName(stepName)
+        const [service, method] = serviceMethod.split('.')
+        if (!service || !method) {
+          throw new Error(
+            `[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`
+          )
+        }
+        await this.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            const rpcName = 'pikkuScenarioGetStubCalls'
+            const calls: Array<{
+              service: string
+              method: string
+              args: unknown[]
+            }> = options?.actor
+              ? await options.actor.invoke(rpcName, { service })
+              : await rpcService.rpcWithWire(rpcName, { service }, {})
+            const matching = (calls ?? []).filter(
+              (c) =>
+                c.service === service &&
+                c.method === method &&
+                (options?.calledWith === undefined ||
+                  JSON.stringify(c.args?.[0]) ===
+                    JSON.stringify(options.calledWith))
+            )
+            const expected = options?.times
+            const ok =
+              expected === undefined
+                ? matching.length > 0
+                : matching.length === expected
+            if (!ok) {
+              const seen =
+                (calls ?? [])
+                  .map(
+                    (c) =>
+                      `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`
+                  )
+                  .join('\n  ') || '(none)'
+              throw new Error(
+                `[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
+                  `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`
+              )
+            }
+          },
+          options
+        )
+      },
+
       // Implement workflow.sleep()
       sleep: async (stepName: string, duration: string | number) => {
         this.verifyStepName(stepName)

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

@@ -8,6 +8,8 @@ export type { WorkflowService } from '../../services/workflow-service.js'
 export type {
   WorkflowStepOptions,
   WorkflowExpectEventuallyOptions,
+  WorkflowExpectErrorOptions,
+  WorkflowExpectServiceOptions,
   WorkflowWireDoRPC,
   WorkflowWireDoInline,
   WorkflowWireSleep,