@pikku/inspector 0.12.69 → 0.12.72

package/src/add/add-file-with-factory.test.ts

@@ -0,0 +1,134 @@
+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 { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+import {
+  serializeInspectorState,
+  deserializeInspectorState,
+} from '../utils/serialize-inspector-state.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ severity, code, message }) => {
+      if (severity !== 'warn') {
+        criticals.push({ code, message })
+      }
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+const inspectSource = async (prefix: string, source: string) => {
+  const rootDir = await mkdtemp(join(tmpdir(), prefix))
+  const file = join(rootDir, 'services.ts')
+  await writeFile(file, source)
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), [file], { rootDir })
+    return { state, criticals }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('pikkuAddonServices — what an addon takes from its parent', () => {
+  test('a name destructured in the body, not the parameter list, is still forwarded', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-body-destructure-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    const { kysely, secrets } = existingServices',
+        '    return { ...existingServices, stripeApi: makeStripe(secrets) }',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    assert.ok(
+      state.addonRequiredParentServices.includes('kysely'),
+      'kysely is read off the parent bag and must be declared as required'
+    )
+    assert.deepEqual(state.addonCreatedServices, ['stripeApi'])
+    assert.equal(state.addonServicesFactorySeen, true)
+  })
+
+  test('an object rest is a binding name, not a service', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-object-rest-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, { kysely, ...parentServices }) => ({',
+        '    ...parentServices,',
+        '    kysely,',
+        '    stripeApi: makeStripe(),',
+        '  })',
+        ')',
+      ].join('\n')
+    )
+
+    assert.deepEqual(state.addonRequiredParentServices, ['kysely'])
+    assert.ok(
+      !state.addonRequiredParentServices.includes('parentServices'),
+      'a rest binding names the leftover bag, not a service the parent provides'
+    )
+  })
+
+  test('a parenthesised return still yields its created services', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-parenthesised-return-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    return ({ ...existingServices, stripeApi: makeStripe() })',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    assert.deepEqual(state.addonCreatedServices, ['stripeApi'])
+    assert.ok(
+      !state.addonRequiredParentServices.includes('stripeApi'),
+      'a service the factory builds is not one the parent has to supply'
+    )
+  })
+
+  test('the addon contract survives a serialize/deserialize round trip', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-round-trip-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    const { kysely } = existingServices',
+        '    return { ...existingServices, stripeApi: makeStripe(kysely) }',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    const restored = deserializeInspectorState(
+      JSON.parse(JSON.stringify(serializeInspectorState(state)))
+    )
+
+    assert.deepEqual(
+      restored.addonRequiredParentServices,
+      state.addonRequiredParentServices
+    )
+    assert.deepEqual(restored.addonCreatedServices, ['stripeApi'])
+    assert.equal(restored.addonServicesFactorySeen, true)
+  })
+})

package/src/add/add-file-with-factory.ts

@@ -13,6 +13,106 @@ const wrapperFunctionMap: Record<string, string> = {
   pikkuServerLifecycle: 'ServerLifecycle',
 }
 
+/**
+ * What an addon's `pikkuAddonServices` factory takes from the parent: the names
+ * destructured off its second parameter, either in the parameter list or from a
+ * `const { … } = existingServices` in the body.
+ */
+const extractForwardedServices = (
+  functionNode: ts.ArrowFunction | ts.FunctionExpression
+): string[] => {
+  const forwarded: string[] = []
+  const secondParam = functionNode.parameters[1]
+  if (!secondParam) return forwarded
+
+  const collectBinding = (pattern: ts.ObjectBindingPattern) => {
+    for (const elem of pattern.elements) {
+      if (elem.dotDotDotToken) continue
+      const name =
+        elem.propertyName && ts.isIdentifier(elem.propertyName)
+          ? elem.propertyName.text
+          : ts.isIdentifier(elem.name)
+            ? elem.name.text
+            : undefined
+      if (name) forwarded.push(name)
+    }
+  }
+
+  if (ts.isObjectBindingPattern(secondParam.name)) {
+    collectBinding(secondParam.name)
+    return forwarded
+  }
+
+  if (!ts.isIdentifier(secondParam.name)) return forwarded
+  const paramName = secondParam.name.text
+  const body = functionNode.body
+  if (!ts.isBlock(body)) return forwarded
+
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isObjectBindingPattern(node.name) &&
+      node.initializer &&
+      ts.isIdentifier(node.initializer) &&
+      node.initializer.text === paramName
+    ) {
+      collectBinding(node.name)
+    }
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(body, visit)
+
+  return forwarded
+}
+
+/**
+ * The service names the factory's returned object literals name. A spread is
+ * skipped — it carries the parent's bag through rather than naming anything —
+ * and a name the factory took off the parent is a forward, not a creation.
+ */
+const extractReturnedServices = (
+  functionNode: ts.ArrowFunction | ts.FunctionExpression
+): string[] => {
+  const returned: string[] = []
+
+  const collect = (expression: ts.Expression) => {
+    while (ts.isParenthesizedExpression(expression)) {
+      expression = expression.expression
+    }
+    if (!ts.isObjectLiteralExpression(expression)) return
+    for (const property of expression.properties) {
+      if (ts.isSpreadAssignment(property)) continue
+      const name = property.name
+      if (name && (ts.isIdentifier(name) || ts.isStringLiteral(name))) {
+        returned.push(name.text)
+      }
+    }
+  }
+
+  const body = functionNode.body
+  if (!ts.isBlock(body)) {
+    collect(body)
+    return returned
+  }
+
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node)
+    ) {
+      return
+    }
+    if (ts.isReturnStatement(node) && node.expression) {
+      collect(node.expression)
+    }
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(body, visit)
+
+  return returned
+}
+
 export const addFileWithFactory = (
   node: ts.Node,
   checker: ts.TypeChecker,
@@ -77,23 +177,15 @@ export const addFileWithFactory = (
 
             // Extract existing services an addon needs from the parent
             // (second parameter of pikkuAddonServices callback)
-            if (
-              wrapperFunctionName === 'pikkuAddonServices' &&
-              functionNode &&
-              functionNode.parameters.length >= 2
-            ) {
-              const secondParam = functionNode.parameters[1]
-              if (secondParam && ts.isObjectBindingPattern(secondParam.name)) {
-                for (const elem of secondParam.name.elements) {
-                  const name =
-                    elem.propertyName && ts.isIdentifier(elem.propertyName)
-                      ? elem.propertyName.text
-                      : ts.isIdentifier(elem.name)
-                        ? elem.name.text
-                        : undefined
-                  if (name) {
-                    state.addonRequiredParentServices.push(name)
-                  }
+            if (wrapperFunctionName === 'pikkuAddonServices' && functionNode) {
+              state.addonServicesFactorySeen = true
+              const forwarded = new Set(extractForwardedServices(functionNode))
+              for (const name of forwarded) {
+                state.addonRequiredParentServices.push(name)
+              }
+              for (const name of extractReturnedServices(functionNode)) {
+                if (!forwarded.has(name)) {
+                  state.addonCreatedServices.push(name)
                 }
               }
             }

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

@@ -161,3 +161,127 @@ export async function doWork() {
     }
   })
 })
+
+describe('add-rpc-invocations — invokedAgentsByFile', () => {
+  test('a body-level runAgent() is attributed to its source file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+export async function askTheHouse() {
+  return runAgent('houseAssistant', { message: 'hi' })
+}
+`,
+      'other.ts': `
+export const unrelated = () => 'no agents here'
+`,
+    })
+    try {
+      const byFile = state.agents.invokedAgentsByFile
+      assert.strictEqual(byFile.size, 1)
+      const [file, agents] = [...byFile.entries()][0]!
+      assert.ok(file.endsWith('caller.ts'))
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('rpc.agent.run() is an agent invocation too', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function askTheHouse() {
+  return rpc.agent.run('houseAssistant', { message: 'hi' })
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('a non-null assertion on the rpc receiver is still an invocation', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { agent: { stream: (name: string, input: unknown) => Promise<unknown> } } | undefined
+export async function askTheHouse() {
+  return rpc!.agent.stream('houseAssistant', { message: 'hi' })
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('multiple agent calls in one file accumulate under that file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+declare const rpc: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function askEveryone() {
+  await runAgent('houseAssistant', {})
+  return rpc.agent.run('gardenAssistant', {})
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents].sort(), [
+        'gardenAssistant',
+        'houseAssistant',
+      ])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('a dynamic agent name is warned about, not recorded', async () => {
+    const warnings: string[] = []
+    const dir = await mkdtemp(join(tmpdir(), 'pikku-agent-invocations-test-'))
+    const path = join(dir, 'caller.ts')
+    await writeFile(
+      path,
+      `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+declare const suffix: string
+export async function askTheHouse() {
+  return runAgent(\`house-\${suffix}\`, {})
+}
+`
+    )
+    const logger = makeLogger()
+    logger.warn = (message: string) => {
+      warnings.push(message)
+    }
+    try {
+      const state = await inspect(logger, [path], { rootDir: dir })
+      assert.strictEqual(state.agents.invokedAgentsByFile.size, 0)
+      assert.ok(warnings.some((w) => w.includes('dynamic agent invocation')))
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('run() on some other receiver is left alone', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const client: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function doWork() {
+  return client.agent.run('notAnAgentCall', {})
+}
+`,
+    })
+    try {
+      assert.strictEqual(state.agents.invokedAgentsByFile.size, 0)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

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

@@ -51,6 +51,33 @@ function extractNamespace(functionRef: string): string | null {
   return null
 }
 
+function agentInvocationName(
+  expression: ts.Expression
+): 'runAgent' | 'streamAgent' | 'rpc.agent.run' | 'rpc.agent.stream' | null {
+  if (ts.isIdentifier(expression)) {
+    if (expression.text === 'runAgent') return 'runAgent'
+    if (expression.text === 'streamAgent') return 'streamAgent'
+    return null
+  }
+  if (!ts.isPropertyAccessExpression(expression)) return null
+  const method = expression.name.text
+  if (method !== 'run' && method !== 'stream') return null
+  const agentReceiver = invocationReceiver(expression.expression)
+  if (
+    !ts.isPropertyAccessExpression(agentReceiver) ||
+    agentReceiver.name.text !== 'agent'
+  ) {
+    return null
+  }
+  const rpcReceiver = invocationReceiver(agentReceiver.expression)
+  const isRpc = ts.isIdentifier(rpcReceiver)
+    ? rpcReceiver.text === 'rpc'
+    : ts.isPropertyAccessExpression(rpcReceiver) &&
+      rpcReceiver.name.text === 'rpc'
+  if (!isRpc) return null
+  return method === 'run' ? 'rpc.agent.run' : 'rpc.agent.stream'
+}
+
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
  * Also detects addon usage via:
@@ -99,6 +126,31 @@ export function addRPCInvocations(
       }
     }
 
+    const agentCall = agentInvocationName(expression)
+    if (agentCall) {
+      const [firstArg] = args
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        const agentName = firstArg.text
+        logger.debug(`• Found ${agentCall}() call: ${agentName}`)
+        const sourceFileName = node.getSourceFile().fileName
+        let byFile = state.agents.invokedAgentsByFile.get(sourceFileName)
+        if (!byFile) {
+          byFile = new Set()
+          state.agents.invokedAgentsByFile.set(sourceFileName, byFile)
+        }
+        byFile.add(agentName)
+      } else if (
+        firstArg &&
+        (ts.isTemplateExpression(firstArg) ||
+          ts.isNoSubstitutionTemplateLiteral(firstArg))
+      ) {
+        logger.warn(`• Found dynamic agent invocation: ${firstArg.getText()}`)
+        logger.warn(
+          `\tYou can only use string literals for agent names, with ' or " and not \``
+        )
+      }
+    }
+
     // Check for rpc.invoke('...') calls
     const invokeReceiver = ts.isPropertyAccessExpression(expression)
       ? invocationReceiver(expression.expression)

package/src/add/add-scenario-step.test.ts

@@ -245,6 +245,67 @@ describe('pikkuScenarioStep', () => {
     }
   })
 
+  test('a step whose prose opens with its own actor is a PKU681 critical', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given(`'shopper' buys an apple`, 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `the reporter already renders the actor as the subject, so this reads "Given shopper 'shopper' buys an apple", got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('an unquoted, capitalised actor opening the prose is caught too', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('Shopper buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `quotes and case are decoration — the subject is still doubled, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a call-site description naming the actor is caught as well as the step name', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper, description: `shopper buys an apple` })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `the description is what actually renders when it is given, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('an actor named mid-sentence is left alone', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sends shopper a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU681').length,
+        0,
+        `only the subject position doubles up; naming someone mid-sentence is ordinary prose, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
   test('a scenario that never asserts is a PKU680 critical', async () => {
     const { criticals, cleanup } = await run([
       "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",

package/src/error-codes.ts

@@ -26,6 +26,7 @@ export enum ErrorCode {
   SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
   SCENARIO_NOT_EXTRACTABLE = 'PKU679',
   SCENARIO_HAS_NO_ASSERTION = 'PKU680',
+  SCENARIO_STEP_PROSE_NAMES_ACTOR = 'PKU681',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
   WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',

package/src/inspector.ts

@@ -83,6 +83,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     wireServicesFactories: new Map(),
     wireServicesMeta: new Map(),
     addonRequiredParentServices: [],
+    addonCreatedServices: [],
+    addonServicesFactorySeen: false,
     addonServerlessIncompatible: new Map(),
     configFactories: new Map(),
     serverLifecycleFactories: new Map(),
@@ -163,6 +165,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     agents: {
       agentsMeta: {},
       files: new Map(),
+      invokedAgentsByFile: new Map(),
     },
     scorers: {
       scorersMeta: {},

package/src/types.ts

@@ -526,6 +526,8 @@ export interface InspectorState {
   wireServicesFactories: PathToNameAndType
   wireServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   addonRequiredParentServices: string[] // services an addon needs from the parent (extracted from pikkuAddonServices 2nd param)
+  addonCreatedServices: string[] // services an addon's own pikkuAddonServices factory builds itself
+  addonServicesFactorySeen: boolean // this project declares a pikkuAddonServices factory, i.e. it is an addon
   addonServerlessIncompatible: Map<string, string[]> // namespace → service names that are serverless-incompatible (scoped per addon)
   configFactories: PathToNameAndType
   serverLifecycleFactories: PathToNameAndType
@@ -634,6 +636,16 @@ export interface InspectorState {
   agents: {
     agentsMeta: AgentsMeta
     files: Map<string, { path: string; exportedName: string }>
+    /**
+     * Agent registry keys named by a `runAgent`/`rpc.agent.run` call in a
+     * function body, keyed by the file the call was written in.
+     *
+     * The lookup those calls perform is in-process, so the agent has to be
+     * registered in the same deployment unit as its caller. Without this the
+     * deploy analyzer only ever saw an agent as its own unit, and a caller in
+     * another unit failed at run time with "AI agent not found".
+     */
+    invokedAgentsByFile: Map<string, Set<string>>
   }
   scorers: {
     scorersMeta: ScorerMeta