@pikku/inspector 0.12.75 → 0.12.82

package/src/add/add-queue-worker.ts

@@ -1,117 +0,0 @@
-import * as ts from 'typescript'
-import {
-  getPropertyValue,
-  getCommonWireMetaData,
-} from '../utils/get-property-value.js'
-import type { AddWiring } from '../types.js'
-import {
-  extractFunctionName,
-  makeContextBasedId,
-} from '../utils/extract-function-name.js'
-import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
-import { ensureInlineWiringFunction } from '../utils/ensure-function-metadata.js'
-import { resolveMiddleware } from '../utils/middleware.js'
-import { extractWireNames } from '../utils/post-process.js'
-import { resolveAddonName } from '../utils/resolve-addon-package.js'
-import { ErrorCode } from '../error-codes.js'
-
-export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
-  if (!ts.isCallExpression(node)) {
-    return
-  }
-
-  const args = node.arguments
-  const firstArg = args[0]
-  const expression = node.expression
-
-  // Check if the call is to addQueueWorker
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireQueueWorker') {
-    return
-  }
-
-  if (!firstArg) {
-    return
-  }
-
-  if (ts.isObjectLiteralExpression(firstArg)) {
-    const obj = firstArg
-
-    const name = getPropertyValue(obj, 'name') as string | null
-    const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'Queue worker', name, logger, checker)
-
-    if (disabled) return
-
-    // --- find the referenced function ---
-    const funcInitializer = getPropertyAssignmentInitializer(
-      obj,
-      'func',
-      true,
-      checker
-    )
-    if (!funcInitializer) {
-      logger.critical(
-        ErrorCode.MISSING_FUNC,
-        `No valid 'func' property for queue processor '${name}'.`
-      )
-      return
-    }
-
-    const extracted = extractFunctionName(
-      funcInitializer,
-      checker,
-      state.rootDir
-    )
-    let pikkuFuncId = extracted.pikkuFuncId
-    if (pikkuFuncId.startsWith('__temp_') && name) {
-      pikkuFuncId = makeContextBasedId('queue', name)
-    }
-
-    const packageName = ts.isIdentifier(funcInitializer)
-      ? resolveAddonName(
-          funcInitializer,
-          checker,
-          state.rpc.wireAddonDeclarations
-        )
-      : null
-
-    if (!name) {
-      logger.critical(
-        ErrorCode.MISSING_QUEUE_NAME,
-        `No 'name' provided for queue processor function '${pikkuFuncId}'.`
-      )
-      return
-    }
-
-    // Register metadata for a func inlined into the wiring (see helper).
-    ensureInlineWiringFunction(
-      state,
-      pikkuFuncId,
-      name,
-      funcInitializer,
-      checker,
-      extracted.isHelper
-    )
-
-    // --- resolve middleware ---
-    const middleware = resolveMiddleware(state, obj, tags, checker)
-
-    // --- track used functions/middleware for service aggregation ---
-    state.serviceAggregation.usedFunctions.add(pikkuFuncId)
-    extractWireNames(middleware).forEach((n) =>
-      state.serviceAggregation.usedMiddleware.add(n)
-    )
-
-    state.queueWorkers.files.add(node.getSourceFile().fileName)
-    state.queueWorkers.meta[name] = {
-      pikkuFuncId,
-      ...(packageName && { packageName }),
-      name,
-      summary,
-      description,
-      errors,
-      tags,
-      middleware,
-    }
-  }
-}

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

@@ -1,287 +0,0 @@
-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 })
-    }
-  })
-
-  test('a non-null assertion on the receiver is still an invocation', async () => {
-    const { state, dir } = await inspectFiles({
-      'caller.ts': `
-declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
-export async function doWork() {
-  return rpc!.invoke('executeVirtualUserRun')
-}
-`,
-    })
-    try {
-      assert.ok(state.rpc.invokedFunctions.has('executeVirtualUserRun'))
-      const invoked = [...state.rpc.invokedFunctionsByFile.values()][0]!
-      assert.deepStrictEqual([...invoked], ['executeVirtualUserRun'])
-    } finally {
-      await rm(dir, { recursive: true, force: true })
-    }
-  })
-
-  test('a parenthesised receiver is still an invocation', async () => {
-    const { state, dir } = await inspectFiles({
-      'caller.ts': `
-declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
-export async function doWork() {
-  return (rpc!).invoke('listTasks')
-}
-`,
-    })
-    try {
-      assert.ok(state.rpc.invokedFunctions.has('listTasks'))
-    } finally {
-      await rm(dir, { recursive: true, force: true })
-    }
-  })
-
-  test('invoke on some other receiver is left alone', async () => {
-    const { state, dir } = await inspectFiles({
-      'caller.ts': `
-declare const client: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
-export async function doWork() {
-  return client!.invoke('notAnRpc')
-}
-`,
-    })
-    try {
-      assert.ok(!state.rpc.invokedFunctions.has('notAnRpc'))
-    } finally {
-      await rm(dir, { recursive: true, force: true })
-    }
-  })
-})
-
-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

@@ -1,221 +0,0 @@
-import * as ts from 'typescript'
-import type { InspectorState, InspectorLogger } from '../types.js'
-import { ErrorCode } from '../error-codes.js'
-
-function hasTypeCast(node: ts.Node): boolean {
-  return ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)
-}
-
-function outerParent(node: ts.Node): ts.Node {
-  let p = node.parent
-  while (p && (ts.isAwaitExpression(p) || ts.isParenthesizedExpression(p))) {
-    p = p.parent
-  }
-  return p
-}
-
-function findCastArg(
-  args: ts.NodeArray<ts.Expression>
-): ts.Expression | undefined {
-  return args.find(hasTypeCast)
-}
-
-/**
- * The `rpc` in `rpc.invoke(...)`, seen through whatever the author wrote to
- * satisfy the type checker.
- *
- * `rpc` is optional on the wire, so a caller that knows it is there reaches for
- * `rpc!.invoke(...)` — and a non-null assertion is a node of its own, not the
- * identifier underneath it. Matching only the bare identifier meant those calls
- * were never recorded as invocations, which is silent rather than loud: the
- * target is not `expose: true`, so nothing else puts it in the registry, and
- * the dispatch fails with "Function not found" at run time on a call site that
- * type-checked. Parentheses are unwrapped for the same reason.
- */
-function invocationReceiver(node: ts.Expression): ts.Expression {
-  let inner = node
-  while (ts.isNonNullExpression(inner) || ts.isParenthesizedExpression(inner)) {
-    inner = inner.expression
-  }
-  return inner
-}
-
-/**
- * Helper to extract namespace from a namespaced function reference like 'ext:hello'
- */
-function extractNamespace(functionRef: string): string | null {
-  const colonIndex = functionRef.indexOf(':')
-  if (colonIndex !== -1) {
-    return functionRef.substring(0, colonIndex)
-  }
-  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:
- * - Namespaced calls: rpc.invoke('namespace:function')
- * - Addon helper: addon('namespace:function')
- */
-export function addRPCInvocations(
-  node: ts.Node,
-  state: InspectorState,
-  logger: InspectorLogger
-) {
-  // Look for call expressions: addon('ext:hello') or rpc.invoke('...')
-  if (ts.isCallExpression(node)) {
-    const { expression, arguments: args } = node
-
-    // Check for ref('name') calls
-    if (ts.isIdentifier(expression) && expression.text === 'ref') {
-      const [firstArg] = args
-      if (firstArg && ts.isStringLiteral(firstArg)) {
-        const functionRef = firstArg.text
-        logger.debug(`• Found addon() call: ${functionRef}`)
-        state.rpc.invokedFunctions.add(functionRef)
-
-        const namespace = extractNamespace(functionRef)
-        if (namespace) {
-          logger.debug(`  → Addon detected: ${namespace}`)
-          state.rpc.usedAddons.add(namespace)
-        }
-      }
-    }
-
-    // Check for workflow('...'), workflowStart('...'), workflowRun('...'), workflowStatus('...'), graphStart('...') calls
-    if (
-      ts.isIdentifier(expression) &&
-      (expression.text === 'workflow' ||
-        expression.text === 'workflowStart' ||
-        expression.text === 'workflowRun' ||
-        expression.text === 'workflowStatus' ||
-        expression.text === 'graphStart')
-    ) {
-      const [firstArg] = args
-      if (firstArg && ts.isStringLiteral(firstArg)) {
-        const workflowName = firstArg.text
-        logger.debug(`• Found ${expression.text}() call: ${workflowName}`)
-        state.workflows.invokedWorkflows.add(workflowName)
-      }
-    }
-
-    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)
-      : undefined
-    if (
-      ts.isPropertyAccessExpression(expression) &&
-      expression.name.text === 'invoke' &&
-      invokeReceiver &&
-      ts.isIdentifier(invokeReceiver) &&
-      invokeReceiver.text === 'rpc'
-    ) {
-      // Skip PKU940 for generated files — they may contain intentional casts
-      // (e.g. the paginated useInfiniteQuery hook in pikku-react-query.gen.ts).
-      const sourceFileName = node.getSourceFile().fileName
-      const isGenerated =
-        sourceFileName.endsWith('.gen.ts') || sourceFileName.endsWith('.gen.js')
-      if (!isGenerated) {
-        if (hasTypeCast(outerParent(node))) {
-          logger.critical(
-            ErrorCode.RPC_INVOCATION_TYPE_CAST,
-            `rpc.invoke() result is type-cast — remove the 'as' expression and rely on Pikku's generated types`
-          )
-        }
-
-        const castArg = findCastArg(args)
-        if (castArg) {
-          logger.critical(
-            ErrorCode.RPC_INVOCATION_TYPE_CAST,
-            `rpc.invoke() has a type cast on an argument — remove the 'as' expression and rely on Pikku's generated types`
-          )
-        }
-      }
-
-      const [firstArg] = args
-      if (firstArg) {
-        if (ts.isStringLiteral(firstArg)) {
-          const functionRef = firstArg.text
-          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}`
-        else if (
-          ts.isTemplateExpression(firstArg) ||
-          ts.isNoSubstitutionTemplateLiteral(firstArg)
-        ) {
-          logger.warn(`• Found dynamic RPC invocation: ${firstArg.getText()}`)
-          logger.warn(
-            `\tYou can only use string literals for RPC function names, with ' or " and not \``
-          )
-        }
-      }
-    }
-  }
-}