@pikku/inspector 0.12.34 → 0.12.36

package/src/add/add-rpc-invocations.test.ts

@@ -0,0 +1,113 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger, InspectorState } from '../types.js'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+async function inspectFiles(
+  files: Record<string, string>
+): Promise<{ state: InspectorState; dir: string }> {
+  const dir = await mkdtemp(join(tmpdir(), 'pikku-rpc-invocations-test-'))
+  const paths: string[] = []
+  for (const [name, source] of Object.entries(files)) {
+    const path = join(dir, name)
+    await writeFile(path, source)
+    paths.push(path)
+  }
+  const state = await inspect(makeLogger(), paths, { rootDir: dir })
+  return { state, dir }
+}
+
+describe('add-rpc-invocations — invokedFunctionsByFile', () => {
+  test('body-level rpc.invoke() is attributed to its source file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> }
+export async function doWork() {
+  return rpc.invoke('console:getSchema')
+}
+`,
+      'other.ts': `
+export const unrelated = () => 'no invocations here'
+`,
+    })
+    try {
+      assert.ok(state.rpc.invokedFunctions.has('console:getSchema'))
+      const byFile = state.rpc.invokedFunctionsByFile
+      assert.strictEqual(byFile.size, 1)
+      const [file, invoked] = [...byFile.entries()][0]!
+      assert.ok(file.endsWith('caller.ts'))
+      assert.deepStrictEqual([...invoked], ['console:getSchema'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('namespaced body invoke joins serviceAggregation.usedFunctions', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> }
+export async function doWork() {
+  await rpc.invoke('ext:goodbye')
+  return rpc.invoke('localHelper')
+}
+`,
+    })
+    try {
+      assert.ok(state.serviceAggregation.usedFunctions.has('ext:goodbye'))
+      assert.ok(!state.serviceAggregation.usedFunctions.has('localHelper'))
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('multiple invocations in one file accumulate under that file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> }
+export async function doWork() {
+  await rpc.invoke('console:getSchema')
+  return rpc.invoke('listTasks')
+}
+`,
+    })
+    try {
+      const invoked = [...state.rpc.invokedFunctionsByFile.values()][0]!
+      assert.deepStrictEqual([...invoked].sort(), [
+        'console:getSchema',
+        'listTasks',
+      ])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('wiring-level ref() lands in invokedFunctions but NOT in the by-file map', async () => {
+    const { state, dir } = await inspectFiles({
+      'wiring.ts': `
+declare const ref: (name: string) => unknown
+export const routes = { stream: { func: ref('console:streamWorkflowRun') } }
+`,
+    })
+    try {
+      assert.ok(state.rpc.invokedFunctions.has('console:streamWorkflowRun'))
+      assert.strictEqual(state.rpc.invokedFunctionsByFile.size, 0)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-rpc-invocations.ts

@@ -115,10 +115,18 @@ export function addRPCInvocations(
           logger.debug(`• Found RPC invocation: ${functionRef}`)
           state.rpc.invokedFunctions.add(functionRef)
 
+          let byFile = state.rpc.invokedFunctionsByFile.get(sourceFileName)
+          if (!byFile) {
+            byFile = new Set()
+            state.rpc.invokedFunctionsByFile.set(sourceFileName, byFile)
+          }
+          byFile.add(functionRef)
+
           const namespace = extractNamespace(functionRef)
           if (namespace) {
             logger.debug(`  → Addon detected: ${namespace}`)
             state.rpc.usedAddons.add(namespace)
+            state.serviceAggregation.usedFunctions.add(functionRef)
           }
         }
         // Handle template literals like `function-${name}`

package/src/add/add-workflow.ts

@@ -34,6 +34,28 @@ function extractStepName(node: ts.Node, checker: ts.TypeChecker): string {
   }
 }
 
+/**
+ * Walk a function body for any `X.expectEventually(...)` call. Used to enforce
+ * that the durable-polling assertion is a scenario-only primitive — regular
+ * workflows must not carry test/assertion semantics.
+ */
+function containsExpectEventuallyCall(node: ts.Node): boolean {
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'expectEventually'
+  ) {
+    return true
+  }
+  let found = false
+  ts.forEachChild(node, (child) => {
+    if (!found && !ts.isFunctionDeclaration(child)) {
+      found = containsExpectEventuallyCall(child)
+    }
+  })
+  return found
+}
+
 /**
  * Recursively check if any step has inline type (non-serializable)
  */
@@ -155,7 +177,9 @@ function getWorkflowInvocations(
               stepName,
               rpcName,
               expectEventually: true,
-              actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+              actor: extractActorFromOptions(
+                args.length >= 5 ? args[4] : undefined
+              ),
             })
             state.rpc.invokedFunctions.add(rpcName)
           }
@@ -194,7 +218,7 @@ function getWorkflowInvocations(
 
 /**
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
- * pikkuUserFlow() calls. Detects workflow registration and extracts metadata.
+ * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
 export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
@@ -209,15 +233,15 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
-  let wrapperType: 'dsl' | 'complex' | 'user-flow' | null = null
+  let wrapperType: 'dsl' | 'complex' | 'scenario' | null = null
   if (expression.text === 'pikkuWorkflowFunc') {
     wrapperType = 'dsl'
   } else if (expression.text === 'pikkuWorkflowComplexFunc') {
     wrapperType = 'complex'
-  } else if (expression.text === 'pikkuUserFlow') {
-    // A user flow is a complex workflow whose steps run as actors over the
+  } else if (expression.text === 'pikkuScenario') {
+    // A scenario is a complex workflow whose steps run as actors over the
     // real transport — same extraction rules as complex, distinct meta.
-    wrapperType = 'user-flow'
+    wrapperType = 'scenario'
   } else {
     return
   }
@@ -292,6 +316,21 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     return
   }
 
+  // expectEventually is a scenario-only assertion primitive — regular
+  // workflows must stay free of test/eval semantics.
+  if (
+    wrapperType !== 'scenario' &&
+    containsExpectEventuallyCall(resolvedFunc)
+  ) {
+    logger.critical(
+      ErrorCode.EXPECT_EVENTUALLY_SCENARIO_ONLY,
+      `Workflow '${workflowName}' calls workflow.expectEventually(), which is only ` +
+        `available in scenarios (pikkuScenario). Move it into a scenario, or drive ` +
+        `the assertion outside the workflow.`
+    )
+    return
+  }
+
   // Track workflow file for wiring generation
   if (exportedName) {
     state.workflows.files.set(pikkuFuncId, {
@@ -368,8 +407,8 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink)
   }
 
-  // Actor names the flow's steps run as (user flows) — powers the console
-  // personas view and the User Flow graph badges.
+  // Actor names the flow's steps run as (scenarios) — powers the console
+  // personas view and the Scenario graph badges.
   const actorNames = [
     ...new Set(
       steps
@@ -390,24 +429,24 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     errors,
     tags,
     expose,
-    userFlow: wrapperType === 'user-flow' ? true : undefined,
+    scenario: wrapperType === 'scenario' ? true : undefined,
     actors: actorNames.length > 0 ? actorNames : undefined,
   }
 
-  // User flows are pure stories of remote RPCs (same rule as client-side CLI
+  // Scenarios are pure stories of remote RPCs (same rule as client-side CLI
   // renderers): the func may only destructure logger/config — everything else
   // must go through actor steps so the flow runs against the TARGET
   // environment, never local services.
   const funcMeta = state.functions.meta[pikkuFuncId]
-  if (wrapperType === 'user-flow' && funcMeta?.services) {
+  if (wrapperType === 'scenario' && funcMeta?.services) {
     const disallowed = funcMeta.services.services.filter(
       (svc) => svc !== 'logger' && svc !== 'config'
     )
     if (disallowed.length > 0) {
       logger.critical(
-        ErrorCode.USER_FLOW_HAS_SERVICES,
-        `User flow '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
-          `User flows may only use 'logger'/'config' — drive everything else through ` +
+        ErrorCode.SCENARIO_HAS_SERVICES,
+        `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+          `Scenarios may only use 'logger'/'config' — drive everything else through ` +
           `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
           `runs against the target environment.`
       )

package/src/add/expect-eventually-scenario-only.test.ts

@@ -0,0 +1,108 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+
+function makeLogger(
+  criticals: Array<{ code: string; message: string }>
+): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: any, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+}
+
+const stepFile = (dir: string) => join(dir, 'my.steps.ts')
+const stepSource = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const getTodos = pikkuSessionlessFunc({',
+  '  func: async ({ logger }) => [{ done: true }],',
+  '})',
+].join('\n')
+
+describe('expectEventually is scenario-only', () => {
+  test('pikkuWorkflowFunc calling expectEventually is a critical error pointing at pikkuScenario', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-ee-wf-'))
+    const wfFile = join(rootDir, 'my.workflow.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const badWorkflow = pikkuWorkflowFunc(async (_, _input, { workflow }) => {',
+        "  await workflow.expectEventually('Wait', 'getTodos', {}, (todos: any) => todos.length > 0)",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      await inspect(makeLogger(criticals), [stepFile(rootDir), wfFile], {
+        rootDir,
+      })
+      const pku675 = criticals.find((c) => c.code === 'PKU675')
+      assert.ok(
+        pku675,
+        `expected a PKU675 critical, got: ${JSON.stringify(criticals)}`
+      )
+      assert.ok(
+        pku675.message.includes('pikkuScenario'),
+        `PKU675 should point users at pikkuScenario, got: ${pku675.message}`
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('pikkuScenario calling expectEventually is allowed and flagged as a scenario', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-ee-sc-'))
+    const wfFile = join(rootDir, 'my.scenario.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuScenario } from '@pikku/core/workflow'",
+        'declare const actors: Record<string, any>',
+        'export const goodFlow = pikkuScenario(async (_, _input, { workflow }) => {',
+        "  await workflow.expectEventually('Wait', 'getTodos', {}, (todos: any) => todos.length > 0, { actor: actors.pm })",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(
+        makeLogger(criticals),
+        [stepFile(rootDir), wfFile],
+        { rootDir }
+      )
+      assert.ok(
+        !criticals.some((c) => c.code === 'PKU675'),
+        `scenarios may use expectEventually; got: ${JSON.stringify(criticals)}`
+      )
+      const meta = (state.workflows.meta as any).goodFlow
+      assert.ok(meta, 'pikkuScenario export should register a workflow')
+      assert.equal(
+        meta.scenario,
+        true,
+        `scenario meta flag should be true, got: ${JSON.stringify(meta)}`
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/error-codes.ts

@@ -21,7 +21,8 @@ export enum ErrorCode {
   MISSING_QUEUE_NAME = 'PKU384',
   MISSING_CHANNEL_NAME = 'PKU400',
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
-  USER_FLOW_HAS_SERVICES = 'PKU673',
+  SCENARIO_HAS_SERVICES = 'PKU673',
+  EXPECT_EVENTUALLY_SCENARIO_ONLY = 'PKU675',
   DYNAMIC_STEP_NAME = 'PKU529',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',

package/src/inspector.ts

@@ -124,6 +124,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       exposedMeta: {},
       exposedFiles: new Map(),
       invokedFunctions: new Set(),
+      invokedFunctionsByFile: new Map(),
       usedAddons: new Set(),
       wireAddonDeclarations: new Map(),
       wireAddonFiles: new Set(),

package/src/types.ts

@@ -482,6 +482,7 @@ export interface InspectorState {
     exposedMeta: Record<string, string>
     exposedFiles: Map<string, { path: string; exportedName: string }>
     invokedFunctions: Set<string>
+    invokedFunctionsByFile: Map<string, Set<string>>
     usedAddons: Set<string>
     wireAddonDeclarations: Map<
       string,

package/src/utils/filter-inspector-state.test.ts

@@ -234,6 +234,7 @@ function createMockInspectorState(): Omit<InspectorState, 'typesLookup'> {
       exposedMeta: {},
       exposedFiles: new Map(),
       invokedFunctions: new Set(),
+      invokedFunctionsByFile: new Map(),
     },
     mcpEndpoints: {
       toolsMeta: {
@@ -1657,3 +1658,233 @@ describe('addonServerlessIncompatible serialization roundtrip', () => {
     assert.strictEqual(restored.addonServerlessIncompatible.size, 0)
   })
 })
+
+describe('addon bootstrap tree-shake', () => {
+  const withAddon = (
+    mutate?: (state: Omit<InspectorState, 'typesLookup'>) => void
+  ) => {
+    const state = createMockInspectorState()
+    state.rpc.wireAddonDeclarations = new Map([
+      ['console', { package: '@pikku/addon-console' }],
+    ])
+    state.rpc.usedAddons = new Set(['console'])
+    state.rpc.invokedFunctions = new Set(['console:streamFunctionTests'])
+    mutate?.(state)
+    return state
+  }
+
+  test('drops an addon nothing kept references', () => {
+    const state = withAddon()
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 0)
+    assert.strictEqual(filtered.rpc.usedAddons.size, 0)
+  })
+
+  test('keeps an addon when a kept wiring targets one of its functions', () => {
+    const state = withAddon((s) => {
+      s.http.meta.get['/console/stream'] = {
+        pikkuFuncId: 'console:streamFunctionTests',
+        route: '/console/stream',
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      } as any
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['console:streamFunctionTests'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+    assert.ok(filtered.rpc.wireAddonDeclarations.has('console'))
+  })
+
+  test('keeps an addon when a kept route ref()-targets one of its functions', () => {
+    const state = withAddon((s) => {
+      s.http.meta.get['/function-tests/stream'] = {
+        pikkuFuncId: 'http:get:/function-tests/stream',
+        refTarget: 'console:streamFunctionTests',
+        route: '/function-tests/stream',
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      } as any
+      s.functions.meta['http:get:/function-tests/stream'] = {
+        services: { optimized: false, services: [] },
+      } as any
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['http:get:/function-tests/stream'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+    assert.ok(filtered.rpc.wireAddonDeclarations.has('console'))
+    assert.ok(
+      filtered.serviceAggregation.usedFunctions.has(
+        'console:streamFunctionTests'
+      )
+    )
+  })
+
+  test('drops the addon when the ref()-wired route is filtered out', () => {
+    const state = withAddon((s) => {
+      s.http.meta.get['/function-tests/stream'] = {
+        pikkuFuncId: 'http:get:/function-tests/stream',
+        refTarget: 'console:streamFunctionTests',
+        route: '/function-tests/stream',
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      } as any
+      s.functions.meta['http:get:/function-tests/stream'] = {
+        services: { optimized: false, services: [] },
+      } as any
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 0)
+    assert.ok(
+      !filtered.serviceAggregation.usedFunctions.has(
+        'console:streamFunctionTests'
+      )
+    )
+  })
+
+  test('keeps an addon when a kept MCP tool targets one of its functions', () => {
+    const state = withAddon((s) => {
+      s.mcpEndpoints.toolsMeta['console:getSchema'] = {
+        name: 'console:getSchema',
+        description: 'addon tool',
+        pikkuFuncId: 'console:getSchema',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      } as any
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['console:getSchema'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+  })
+
+  test('keeps an addon when a kept agent lists one of its functions as a tool', () => {
+    const state = withAddon((s) => {
+      s.agents = s.agents ?? ({ agentsMeta: {} } as any)
+      s.agents.agentsMeta['support-agent'] = {
+        name: 'support-agent',
+        pikkuFuncId: 'supportAgent',
+        tools: ['console:getSchema'],
+        tags: [],
+      } as any
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['support-agent'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+  })
+
+  test('keeps an addon when a kept function body-invokes it', () => {
+    const state = withAddon((s) => {
+      s.rpc.invokedFunctionsByFile = new Map([
+        ['/test/project/src/api/users.ts', new Set(['console:getSchema'])],
+      ])
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+  })
+
+  test('a kept-file body invoke joins the filtered usedFunctions', () => {
+    const state = withAddon((s) => {
+      s.rpc.invokedFunctionsByFile = new Map([
+        ['/test/project/src/api/users.ts', new Set(['console:getSchema'])],
+      ])
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.ok(
+      filtered.serviceAggregation.usedFunctions.has('console:getSchema')
+    )
+  })
+
+  test('drops an addon body-invoked only from filtered-out files', () => {
+    const state = withAddon((s) => {
+      s.rpc.invokedFunctionsByFile = new Map([
+        ['/test/project/src/admin/settings.ts', new Set(['console:getSchema'])],
+      ])
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 0)
+  })
+
+  test('unfiltered state keeps all addons', () => {
+    const state = withAddon()
+    const filtered = filterInspectorState(state, {}, mockLogger)
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+  })
+})
+
+describe('invokedFunctionsByFile serialization', () => {
+  test('round-trips through serialize/deserialize', () => {
+    const state = getInitialInspectorState('/test/project')
+    state.rpc.invokedFunctionsByFile = new Map([
+      ['/test/project/src/api/users.ts', new Set(['console:getSchema'])],
+      [
+        '/test/project/src/api/tasks.ts',
+        new Set(['listTasks', 'console:runAgent']),
+      ],
+    ])
+    const restored = deserializeInspectorState(
+      JSON.parse(JSON.stringify(serializeInspectorState(state as any)))
+    )
+    assert.ok(restored.rpc.invokedFunctionsByFile instanceof Map)
+    assert.strictEqual(restored.rpc.invokedFunctionsByFile.size, 2)
+    assert.deepStrictEqual(
+      [
+        ...restored.rpc.invokedFunctionsByFile.get(
+          '/test/project/src/api/tasks.ts'
+        )!,
+      ].sort(),
+      ['console:runAgent', 'listTasks']
+    )
+  })
+
+  test('deserializing legacy state without the field yields an empty Map', () => {
+    const serialized = JSON.parse(
+      JSON.stringify(
+        serializeInspectorState(
+          getInitialInspectorState('/test/project') as any
+        )
+      )
+    )
+    delete serialized.rpc.invokedFunctionsByFile
+    const restored = deserializeInspectorState(serialized)
+    assert.ok(restored.rpc.invokedFunctionsByFile instanceof Map)
+    assert.strictEqual(restored.rpc.invokedFunctionsByFile.size, 0)
+  })
+})