@pikku/inspector 0.12.33 → 0.12.35

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

@@ -16,7 +16,10 @@ import {
   getPropertyValue,
 } from '../utils/get-property-value.js'
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
-import { getSourceText } from '../utils/workflow/dsl/patterns.js'
+import {
+  getSourceText,
+  extractActorFromOptions,
+} from '../utils/workflow/dsl/patterns.js'
 
 /**
  * Extract a workflow step's display name without letting a non-static name
@@ -86,7 +89,8 @@ export function collectInvokedRPCs(
 }
 
 /**
- * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
+ * workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(
   node: ts.Node,
@@ -100,7 +104,12 @@ function getWorkflowInvocations(
     const { name } = node
 
     // Check if this is accessing 'do' or 'sleep' property
-    if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
+    if (
+      name.text === 'do' ||
+      name.text === 'sleep' ||
+      name.text === 'cancel' ||
+      name.text === 'expectEventually'
+    ) {
       // Check if the parent is a call expression
       const parent = node.parent
       if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -125,6 +134,7 @@ function getWorkflowInvocations(
               type: 'rpc',
               stepName,
               rpcName,
+              actor: extractActorFromOptions(optionsArg),
             })
             state.rpc.invokedFunctions.add(rpcName)
           } else if (isFunctionLike(secondArg)) {
@@ -135,6 +145,20 @@ function getWorkflowInvocations(
               description: description || '<dynamic>',
             })
           }
+        } else if (name.text === 'expectEventually' && args.length >= 4) {
+          // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
+          const stepName = extractStepName(args[0], checker)
+          if (isStringLike(args[1], checker)) {
+            const rpcName = extractStringLiteral(args[1], checker)
+            steps.push({
+              type: 'rpc',
+              stepName,
+              rpcName,
+              expectEventually: true,
+              actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+            })
+            state.rpc.invokedFunctions.add(rpcName)
+          }
         } else if (name.text === 'sleep' && args.length >= 2) {
           // workflow.sleep(stepName, duration)
           const stepNameArg = args[0]
@@ -337,10 +361,23 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
   // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
   // with identifier args, etc.) are still registered as invoked functions.
+  // When DSL extraction already produced steps this pass is registration-only:
+  // appending to `steps` would duplicate nodes and clobber the graph.
   if (wrapperType !== 'dsl') {
-    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+    const sink: WorkflowStepMeta[] = steps.length > 0 ? [] : steps
+    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.
+  const actorNames = [
+    ...new Set(
+      steps
+        .map((s) => ('actor' in s ? s.actor : undefined))
+        .filter((a): a is string => typeof a === 'string')
+    ),
+  ]
+
   state.workflows.meta[workflowName] = {
     pikkuFuncId,
     name: workflowName,
@@ -354,6 +391,7 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     tags,
     expose,
     userFlow: wrapperType === 'user-flow' ? true : undefined,
+    actors: actorNames.length > 0 ? actorNames : undefined,
   }
 
   // User flows are pure stories of remote RPCs (same rule as client-side CLI

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)
+  })
+})

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

@@ -468,6 +468,11 @@ export function filterInspectorState(
           filteredState.serviceAggregation.usedFunctions.add(
             routeMeta.pikkuFuncId
           )
+          if (routeMeta.refTarget) {
+            filteredState.serviceAggregation.usedFunctions.add(
+              routeMeta.refTarget
+            )
+          }
           // For workflow/agent routes, also add the base name
           // so the workflow/agent definition survives pruning
           const colonIdx = routeMeta.pikkuFuncId.indexOf(':')
@@ -1105,6 +1110,57 @@ export function filterInspectorState(
     filteredState.serviceAggregation.requiredServices.add('queueService')
   }
 
+  if ((filteredState.rpc.wireAddonDeclarations?.size ?? 0) > 0) {
+    const referencedIds = new Set<string>(
+      filteredState.serviceAggregation.usedFunctions
+    )
+    const keptFiles = new Set<string>()
+    for (const funcId of filteredState.serviceAggregation.usedFunctions) {
+      const file = filteredState.functions.files.get(funcId)
+      if (file?.path) keptFiles.add(file.path)
+    }
+    for (const [file, invoked] of state.rpc.invokedFunctionsByFile ??
+      new Map<string, Set<string>>()) {
+      if (!keptFiles.has(file)) continue
+      for (const id of invoked) {
+        referencedIds.add(id)
+        if (id.includes(':')) {
+          filteredState.serviceAggregation.usedFunctions.add(id)
+        }
+      }
+    }
+    for (const toolMeta of Object.values(
+      filteredState.mcpEndpoints?.toolsMeta ?? {}
+    ) as Array<{ pikkuFuncId?: string }>) {
+      if (toolMeta.pikkuFuncId) referencedIds.add(toolMeta.pikkuFuncId)
+    }
+    for (const agentMeta of Object.values(
+      filteredState.agents?.agentsMeta ?? {}
+    ) as Array<{ tools?: string[] }>) {
+      for (const tool of agentMeta.tools ?? []) referencedIds.add(tool)
+    }
+    const keptNamespaces = new Set<string>()
+    for (const namespace of filteredState.rpc.wireAddonDeclarations.keys()) {
+      const prefix = `${namespace}:`
+      for (const id of referencedIds) {
+        if (id.startsWith(prefix)) {
+          keptNamespaces.add(namespace)
+          break
+        }
+      }
+    }
+    filteredState.rpc.wireAddonDeclarations = new Map(
+      [...filteredState.rpc.wireAddonDeclarations].filter(([namespace]) =>
+        keptNamespaces.has(namespace)
+      )
+    )
+    filteredState.rpc.usedAddons = new Set(
+      [...filteredState.rpc.usedAddons].filter((namespace) =>
+        keptNamespaces.has(namespace)
+      )
+    )
+  }
+
   // Recalculate requiredServices based on filtered functions/middleware/permissions
   // Need to cast to InspectorState temporarily for aggregateRequiredServices
   const stateForAggregation = filteredState as InspectorState

package/src/utils/load-addon-functions-meta.ts

@@ -200,6 +200,7 @@ export async function loadAddonFunctionsMeta(
         // No variables meta — that's fine
       }
       // Load addon serverlessIncompatible service names from pikku-addon-meta.gen.json
+      let loadedParentServices = false
       try {
         const addonMetaPath = require.resolve(
           `${decl.package}/.pikku/console/pikku-addon-meta.gen.json`
@@ -218,29 +219,38 @@ export async function loadAddonFunctionsMeta(
             `Addon '${namespace}' marks [${addonMeta.serverlessIncompatible.join(', ')}] as serverless-incompatible`
           )
         }
-      } catch {
-        // No addon meta or no serverlessIncompatible declared — that's fine
-      }
-
-      // Load addon required parent services from pikku-services.gen
-      try {
-        const servicesGenPath = require.resolve(
-          `${decl.package}/.pikku/pikku-services.gen.js`
-        )
-        const servicesModule = await import(servicesGenPath)
         if (
-          servicesModule.requiredParentServices &&
-          Array.isArray(servicesModule.requiredParentServices)
+          Array.isArray(addonMeta.requiredParentServices) &&
+          addonMeta.requiredParentServices.length > 0
         ) {
-          for (const service of servicesModule.requiredParentServices) {
+          for (const service of addonMeta.requiredParentServices) {
             state.addonRequiredParentServices.push(service)
           }
+          loadedParentServices = true
           logger.debug(
-            `Loaded ${servicesModule.requiredParentServices.length} required parent services for '${namespace}' from ${decl.package}`
+            `Loaded ${addonMeta.requiredParentServices.length} required parent services for '${namespace}' from addon meta`
           )
         }
-      } catch {
-        // No services gen — addon may not have requiredParentServices
+      } catch {}
+
+      if (!loadedParentServices) {
+        try {
+          const servicesGenPath = require.resolve(
+            `${decl.package}/.pikku/pikku-services.gen.js`
+          )
+          const servicesModule = await import(servicesGenPath)
+          if (
+            servicesModule.requiredParentServices &&
+            Array.isArray(servicesModule.requiredParentServices)
+          ) {
+            for (const service of servicesModule.requiredParentServices) {
+              state.addonRequiredParentServices.push(service)
+            }
+            logger.debug(
+              `Loaded ${servicesModule.requiredParentServices.length} required parent services for '${namespace}' from ${decl.package}`
+            )
+          }
+        } catch {}
       }
 
       try {