@pikku/inspector 0.12.10 → 0.12.12

package/src/add/add-functions.test.ts

@@ -0,0 +1,318 @@
+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 { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+describe('addFunctions duplicate name handling', () => {
+  test('logs a critical error when function name is duplicated across files', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-duplicate-function-'))
+    const fileA = join(rootDir, 'a.ts')
+    const fileB = join(rootDir, 'b.ts')
+
+    await writeFile(
+      fileA,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      fileB,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: (code: ErrorCode, message: string) => {
+        criticals.push({ code, message })
+      },
+      hasCriticalErrors: () => criticals.length > 0,
+    }
+
+    try {
+      const state = await inspect(logger, [fileA, fileB], { rootDir })
+      const nameCollision = criticals.find(
+        (entry) => entry.code === ErrorCode.DUPLICATE_FUNCTION_NAME
+      )
+      assert.ok(nameCollision)
+      assert.match(nameCollision!.message, /createUser/)
+      assert.strictEqual(state.rpc.internalMeta['createUser'], 'createUser')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('allows same base function name across files when versions differ', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-versioned-function-'))
+    const fileA = join(rootDir, 'a.ts')
+    const fileB = join(rootDir, 'b.ts')
+
+    await writeFile(
+      fileA,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  version: 1,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      fileB,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  version: 2,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: (code: ErrorCode, message: string) => {
+        criticals.push({ code, message })
+      },
+      hasCriticalErrors: () => criticals.length > 0,
+    }
+
+    try {
+      const state = await inspect(logger, [fileA, fileB], { rootDir })
+      const nameCollision = criticals.find(
+        (entry) => entry.code === ErrorCode.DUPLICATE_FUNCTION_NAME
+      )
+      assert.equal(nameCollision, undefined)
+      assert.strictEqual(state.rpc.internalMeta['createUser'], 'createUser@v2')
+      assert.ok(state.functions.meta['createUser@v1'])
+      assert.ok(state.functions.meta['createUser@v2'])
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('strips VN suffix so createUserV1 + version:1 groups with createUser as createUser@v1', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-vn-suffix-'))
+    const fileV1 = join(rootDir, 'create-user-v1.ts')
+    const fileLatest = join(rootDir, 'create-user.ts')
+
+    await writeFile(
+      fileV1,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUserV1 = pikkuFunc({',
+        '  version: 1,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      fileLatest,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      const state = await inspect(logger, [fileV1, fileLatest], { rootDir })
+      // V1 suffix stripped: createUserV1 + version:1 → createUser@v1
+      assert.ok(
+        state.functions.meta['createUser@v1'],
+        'createUser@v1 should exist'
+      )
+      assert.strictEqual(state.functions.meta['createUser@v1']!.version, 1)
+      // Unversioned createUser auto-promoted to createUser@v2
+      assert.ok(
+        state.functions.meta['createUser@v2'],
+        'createUser@v2 should exist'
+      )
+      assert.strictEqual(state.functions.meta['createUser@v2']!.version, 2)
+      // No stale createUserV1@v1 entry
+      assert.strictEqual(state.functions.meta['createUserV1@v1'], undefined)
+      // Latest alias points to v2
+      assert.strictEqual(state.rpc.internalMeta['createUser'], 'createUser@v2')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('logs a critical error when exposed function name is duplicated across files', async () => {
+    const rootDir = await mkdtemp(
+      join(tmpdir(), 'pikku-exposed-duplicate-function-')
+    )
+    const fileA = join(rootDir, 'a.ts')
+    const fileB = join(rootDir, 'b.ts')
+
+    await writeFile(
+      fileA,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  expose: true,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      fileB,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  expose: true,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: (code: ErrorCode, message: string) => {
+        criticals.push({ code, message })
+      },
+      hasCriticalErrors: () => criticals.length > 0,
+    }
+
+    try {
+      await inspect(logger, [fileA, fileB], { rootDir })
+      const nameCollision = criticals.find(
+        (entry) => entry.code === ErrorCode.DUPLICATE_FUNCTION_NAME
+      )
+      assert.ok(nameCollision)
+      assert.match(
+        nameCollision!.message,
+        /Function name 'createUser' is not unique/
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('addFunctions implementationHash', () => {
+  test('records a stable implementation hash for an inline function', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-function-hash-inline-'))
+    const file = join(rootDir, 'inline.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  expose: true,',
+        '  func: async ({ logger }, input: { name: string }) => {',
+        "    logger.info('create user')",
+        '    return { ok: true, name: input.name }',
+        '  }',
+        '})',
+      ].join('\n')
+    )
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      const first = await inspect(logger, [file], { rootDir })
+      const second = await inspect(logger, [file], { rootDir })
+      const firstHash = first.functions.meta['createUser']?.implementationHash
+      const secondHash = second.functions.meta['createUser']?.implementationHash
+
+      assert.match(firstHash ?? '', /^[0-9a-f]{16}$/)
+      assert.strictEqual(firstHash, secondHash)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('changes when a referenced handler implementation changes', async () => {
+    const rootDir = await mkdtemp(
+      join(tmpdir(), 'pikku-function-hash-referenced-')
+    )
+    const file = join(rootDir, 'referenced.ts')
+
+    const writeSource = async (bodyLine: string) => {
+      await writeFile(
+        file,
+        [
+          "import { pikkuFunc } from '@pikku/core'",
+          '',
+          'const handler = async () => {',
+          `  ${bodyLine}`,
+          '  return { ok: true }',
+          '}',
+          '',
+          'export const createUser = pikkuFunc({',
+          '  func: handler,',
+          '})',
+        ].join('\n')
+      )
+    }
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      await writeSource("console.log('first')")
+      const first = await inspect(logger, [file], { rootDir })
+
+      await writeSource("console.log('second')")
+      const second = await inspect(logger, [file], { rootDir })
+
+      assert.notStrictEqual(
+        first.functions.meta['createUser']?.implementationHash,
+        second.functions.meta['createUser']?.implementationHash
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-functions.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import type { AddWiring, SchemaRef } from '../types.js'
+import type { AddWiring, InspectorState, SchemaRef } from '../types.js'
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
 import type { TypesMap } from '../types-map.js'
 import {
@@ -9,11 +9,12 @@ import {
 import { extractFunctionNode } from '../utils/extract-function-node.js'
 import { extractUsedWires } from '../utils/extract-services.js'
 import type { FunctionServicesMeta } from '@pikku/core'
-import { formatVersionedId } from '@pikku/core'
+import { formatVersionedId, parseVersionedId } from '@pikku/core'
 import {
   getPropertyValue,
   getCommonWireMetaData,
 } from '../utils/get-property-value.js'
+import { canonicalJSON, hashString } from '../utils/hash.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
@@ -287,6 +288,54 @@ function unwrapPromise(checker: ts.TypeChecker, type: ts.Type): ts.Type {
   return type
 }
 
+const resolveExistingFunctionSource = (
+  state: InspectorState,
+  pikkuFuncId: string
+): string | null => {
+  return (
+    state.functions.meta[pikkuFuncId]?.sourceFile ||
+    state.rpc.internalFiles.get(pikkuFuncId)?.path ||
+    null
+  )
+}
+
+const areCompatibleFunctionIds = (
+  existingId: string,
+  incomingId: string
+): boolean => {
+  if (existingId === incomingId) {
+    return true
+  }
+
+  const existingParsed = parseVersionedId(existingId)
+  const incomingParsed = parseVersionedId(incomingId)
+
+  return existingParsed.baseName === incomingParsed.baseName
+}
+
+function printNode(node: ts.Node): string {
+  return ts
+    .createPrinter({ removeComments: true })
+    .printNode(ts.EmitHint.Unspecified, node, node.getSourceFile())
+}
+
+function computeImplementationHash(args: {
+  wrapper: string
+  handler: ts.ArrowFunction | ts.FunctionExpression
+  objectNode?: ts.ObjectLiteralExpression
+  isDirectFunction: boolean
+}): string {
+  const { wrapper, handler, objectNode, isDirectFunction } = args
+  return hashString(
+    canonicalJSON({
+      wrapper,
+      isDirectFunction,
+      handler: printNode(handler),
+      config: objectNode ? printNode(objectNode) : null,
+    })
+  )
+}
+
 /**
  * Inspect pikkuFunc calls, extract input/output and first-arg destructuring,
  * then push into state.functions.meta.
@@ -541,11 +590,17 @@ export const addFunctions: AddWiring = (
   }
 
   if (version !== undefined) {
-    const baseName = explicitName || exportedName || pikkuFuncId
+    let baseName = explicitName || exportedName || pikkuFuncId
+    // Strip trailing VN suffix if it matches the version (e.g. getDataV1 + version:1 → getData@v1)
+    const vSuffix = `V${version}`
+    if (baseName.endsWith(vSuffix) && baseName.length > vSuffix.length) {
+      baseName = baseName.slice(0, -vSuffix.length)
+    }
     pikkuFuncId = formatVersionedId(baseName, version)
   }
 
   const isMCPToolFunc = expression.text === 'pikkuMCPToolFunc'
+  const isListFunc = expression.text === 'pikkuListFunc'
   const mcpEnabled = mcp || isMCPToolFunc
 
   // Pick the handler: use resolvedFunc when it exists and is a function, otherwise fall back to handlerNode
@@ -618,7 +673,33 @@ export const addFunctions: AddWiring = (
     inputNames = [schemaName]
     state.schemaLookup.set(schemaName, inputSchemaRef)
     state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
-  } else if (genericTypes.length >= 1 && genericTypes[0]) {
+  } else if (isListFunc && genericTypes.length >= 1 && genericTypes[0]) {
+    const inputAliasName = `${capitalizedName}Input`
+    const filterType = genericTypes[0]
+    const filterTypeText = checker.typeToString(
+      filterType,
+      undefined,
+      ts.TypeFormatFlags.NoTruncation
+    )
+    const refs = resolveTypeImports(
+      filterType,
+      state.functions.typesMap,
+      true,
+      checker
+    )
+    state.functions.typesMap.addCustomType(
+      inputAliasName,
+      `{ cursor?: string; limit?: number; sort?: Array<{ column: string; direction: 'asc' | 'desc' }>; filter?: unknown; search?: string; } & ${filterTypeText}`,
+      [...new Set(refs)]
+    )
+    inputNames = [inputAliasName]
+    const secondParam = handler.parameters[1]
+    if (secondParam) {
+      inputTypes = [checker.getTypeAtLocation(secondParam)]
+    } else {
+      inputTypes = [filterType]
+    }
+  } else if (!isListFunc && genericTypes.length >= 1 && genericTypes[0]) {
     // Fall back to extracting from generic type arguments
     const result = getNamesAndTypes(
       checker,
@@ -654,7 +735,27 @@ export const addFunctions: AddWiring = (
     outputNames = [schemaName]
     state.schemaLookup.set(schemaName, outputSchemaRef)
     state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
-  } else if (genericTypes.length >= 2) {
+  } else if (isListFunc && genericTypes.length >= 2 && genericTypes[1]) {
+    const outputAliasName = `${capitalizedName}Output`
+    const rowType = genericTypes[1]
+    const rowTypeText = checker.typeToString(
+      rowType,
+      undefined,
+      ts.TypeFormatFlags.NoTruncation
+    )
+    const refs = resolveTypeImports(
+      rowType,
+      state.functions.typesMap,
+      true,
+      checker
+    )
+    state.functions.typesMap.addCustomType(
+      outputAliasName,
+      `{ rows: Array<${rowTypeText}>; nextCursor: string | null; totalCount?: number; }`,
+      [...new Set(refs)]
+    )
+    outputNames = [outputAliasName]
+  } else if (!isListFunc && genericTypes.length >= 2) {
     outputNames = getNamesAndTypes(
       checker,
       state.functions.typesMap,
@@ -731,6 +832,56 @@ export const addFunctions: AddWiring = (
     state.typesLookup.set(pikkuFuncId, inputTypes)
   }
 
+  const sourceFile = node.getSourceFile().fileName
+  const existingFunction = state.functions.meta[pikkuFuncId]
+  if (
+    existingFunction &&
+    existingFunction.sourceFile &&
+    existingFunction.sourceFile !== sourceFile
+  ) {
+    logger.critical(
+      ErrorCode.DUPLICATE_FUNCTION_NAME,
+      `Function name '${name}' is not unique. ` +
+        `'${pikkuFuncId}' is already defined in '${existingFunction.sourceFile}' and cannot be redefined in '${sourceFile}'.`
+    )
+    return
+  }
+
+  if (exportedName || explicitName) {
+    const existingInternal = state.rpc.internalMeta[name]
+    if (
+      existingInternal &&
+      !areCompatibleFunctionIds(existingInternal, pikkuFuncId)
+    ) {
+      const existingSource =
+        resolveExistingFunctionSource(state, existingInternal) || 'unknown file'
+      logger.critical(
+        ErrorCode.DUPLICATE_FUNCTION_NAME,
+        `Function name '${name}' is not unique. ` +
+          `It already points to '${existingInternal}' in '${existingSource}', but '${pikkuFuncId}' in '${sourceFile}' tried to use the same name.`
+      )
+      return
+    }
+
+    if (expose) {
+      const existingExposed = state.rpc.exposedMeta[name]
+      if (
+        existingExposed &&
+        !areCompatibleFunctionIds(existingExposed, pikkuFuncId)
+      ) {
+        const existingSource =
+          resolveExistingFunctionSource(state, existingExposed) ||
+          'unknown file'
+        logger.critical(
+          ErrorCode.DUPLICATE_FUNCTION_NAME,
+          `Exposed function name '${name}' is not unique. ` +
+            `It already points to '${existingExposed}' in '${existingSource}', but '${pikkuFuncId}' in '${sourceFile}' tried to use the same name.`
+        )
+        return
+      }
+    }
+  }
+
   // --- resolve middleware ---
   let middleware = objectNode
     ? resolveMiddleware(state, objectNode, tags, checker)
@@ -772,6 +923,12 @@ export const addFunctions: AddWiring = (
   }
 
   const sessionless = expression.text !== 'pikkuFunc'
+  const implementationHash = computeImplementationHash({
+    wrapper: expression.text,
+    handler,
+    objectNode,
+    isDirectFunction,
+  })
 
   state.functions.meta[pikkuFuncId] = {
     pikkuFuncId,
@@ -792,6 +949,7 @@ export const addFunctions: AddWiring = (
     deploy: deploy || undefined,
     approvalRequired: approvalRequired || undefined,
     approvalDescription: approvalDescription || undefined,
+    implementationHash,
     version,
     title,
     tags: tags || undefined,
@@ -801,7 +959,7 @@ export const addFunctions: AddWiring = (
     middleware,
     permissions,
     isDirectFunction,
-    sourceFile: node.getSourceFile().fileName,
+    sourceFile,
     exportedName: exportedName || undefined,
   }
 

package/src/add/add-gateway.ts

@@ -70,7 +70,11 @@ export const addGateway: AddWiring = (
   }
 
   const packageName = ts.isIdentifier(funcInitializer)
-    ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
+    ? resolveAddonName(
+        funcInitializer,
+        checker,
+        state.rpc.wireAddonDeclarations
+      )
     : null
 
   if (!nameValue || !typeValue) {

package/src/add/add-http-route.ts

@@ -18,6 +18,7 @@ import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
 import { resolveHTTPPermissionsFromObject } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
+import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
 import { ErrorCode } from '../error-codes.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
@@ -204,6 +205,22 @@ export function registerHTTPRoute({
     funcName = makeContextBasedId('http', method, fullRoute)
   }
 
+  let refAddonTarget: string | null = null
+  if (
+    ts.isCallExpression(funcInitializer) &&
+    ts.isIdentifier(funcInitializer.expression) &&
+    funcInitializer.expression.text === 'ref'
+  ) {
+    const [firstArg] = funcInitializer.arguments
+    if (
+      firstArg &&
+      ts.isStringLiteral(firstArg) &&
+      firstArg.text.includes(':')
+    ) {
+      refAddonTarget = firstArg.text
+    }
+  }
+
   const packageName = ts.isIdentifier(funcInitializer)
     ? resolveAddonName(
         funcInitializer,
@@ -212,6 +229,16 @@ export function registerHTTPRoute({
       )
     : null
 
+  if (refAddonTarget) {
+    const targetMeta = resolveFunctionMeta(state, refAddonTarget)
+    if (!targetMeta) {
+      logger.warn(
+        `Skipping route '${fullRoute}': addon function metadata for '${refAddonTarget}' is not available yet.`
+      )
+      return
+    }
+  }
+
   ensureFunctionMetadata(
     state,
     funcName,
@@ -222,7 +249,7 @@ export function registerHTTPRoute({
   )
 
   // Lookup existing function metadata
-  const fnMeta = state.functions.meta[funcName]
+  const fnMeta = resolveFunctionMeta(state, funcName)
   if (!fnMeta) {
     logger.critical(
       ErrorCode.FUNCTION_METADATA_NOT_FOUND,
@@ -246,12 +273,32 @@ export function registerHTTPRoute({
 
   const input = fnMeta.inputs?.[0] || null
 
-  // Validate that route params and query params exist in function input type
-  if (params.length > 0 || query.length > 0) {
-    const inputTypes = state.typesLookup.get(funcName)
+  const getRouteInputKeys = (): string[] | null => {
+    const targetFuncName = refAddonTarget ?? funcName
+    const inputTypes = state.typesLookup.get(targetFuncName)
     if (inputTypes && inputTypes.length > 0) {
-      const inputKeys = extractTypeKeys(inputTypes[0])
+      return extractTypeKeys(inputTypes[0])
+    }
+
+    const targetMeta = resolveFunctionMeta(state, targetFuncName)
+    if (targetMeta?.inputSchemaName) {
+      const schema = state.schemas[targetMeta.inputSchemaName] as any
+      const properties = schema?.properties
+      if (properties && typeof properties === 'object') {
+        return Object.keys(properties)
+      }
+    }
 
+    return null
+  }
+
+  // Validate that route params and query params exist in function input type
+  if (params.length > 0 || query.length > 0) {
+    const inputKeys = getRouteInputKeys()
+    if (!inputKeys) {
+      // Input shape isn't inspectable at this phase (e.g. addon ref or opaque handler).
+      // Skip param/query validation rather than emitting a false positive.
+    } else {
       // Check path params
       if (params.length > 0) {
         const missingParams = params.filter((p) => !inputKeys.includes(p))
@@ -259,7 +306,7 @@ export function registerHTTPRoute({
           logger.critical(
             ErrorCode.ROUTE_PARAM_MISMATCH,
             `Route '${fullRoute}' has path parameter(s) [${missingParams.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
+              `not found in function '${refAddonTarget ?? funcName}' input type. ` +
               `Input type has: [${inputKeys.join(', ')}]`
           )
           return
@@ -273,7 +320,7 @@ export function registerHTTPRoute({
           logger.critical(
             ErrorCode.ROUTE_QUERY_MISMATCH,
             `Route '${fullRoute}' has query parameter(s) [${missingQuery.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
+              `not found in function '${refAddonTarget ?? funcName}' input type. ` +
               `Input type has: [${inputKeys.join(', ')}]`
           )
           return