@pikku/inspector 0.7.0 → 0.7.1

package/src/add-functions.ts

@@ -0,0 +1,376 @@
+import * as ts from 'typescript'
+import { InspectorState, InspectorFilters } from './types.js'
+import { TypesMap } from './types-map.js'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+} from './utils.js'
+import { FunctionServicesMeta } from '@pikku/core'
+
+const isValidVariableName = (name: string) => {
+  const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+  return regex.test(name)
+}
+
+const nullifyTypes = (type: string | null) => {
+  if (
+    type === 'void' ||
+    type === 'undefined' ||
+    type === 'unknown' ||
+    type === 'any'
+  ) {
+    return null
+  }
+  return type
+}
+
+const resolveTypeImports = (
+  type: ts.Type,
+  resolvedTypes: TypesMap,
+  isCustom: boolean
+): string[] => {
+  const types: string[] = []
+
+  const visitType = (currentType: ts.Type) => {
+    const symbol = currentType.aliasSymbol || currentType.getSymbol()
+
+    if (symbol) {
+      const declarations = symbol.getDeclarations()
+      const declaration = declarations?.[0]
+      if (declaration) {
+        const sourceFile = declaration.getSourceFile()
+        const path = sourceFile.fileName
+
+        // Skip built-in utility types or TypeScript lib types
+        if (
+          !path.includes('node_modules/typescript') &&
+          symbol.getName() !== '__type' &&
+          !isPrimitiveType(currentType)
+        ) {
+          const originalName = symbol.getName()
+          // Check if the type is already in the map
+          let uniqueName = resolvedTypes.exists(originalName, path)
+          if (!uniqueName) {
+            if (isCustom) {
+              uniqueName = resolvedTypes.addUniqueType(originalName, path)
+            } else {
+              resolvedTypes.addType(originalName, path)
+              uniqueName = originalName
+            }
+          }
+          types.push(uniqueName)
+        }
+      }
+    }
+
+    if (isCustom) {
+      // Handle nested utility types like Partial, Pick, etc.
+      if (currentType.aliasTypeArguments) {
+        currentType.aliasTypeArguments.forEach(visitType)
+      }
+
+      // Handle intersections and unions
+      if (currentType.isUnionOrIntersection()) {
+        currentType.types.forEach(visitType)
+      }
+
+      // Handle object types with type arguments
+      if (
+        currentType.flags & ts.TypeFlags.Object &&
+        (currentType as ts.ObjectType).objectFlags & ts.ObjectFlags.Reference
+      ) {
+        const typeRef = currentType as ts.TypeReference
+        typeRef.typeArguments?.forEach(visitType)
+      }
+    }
+  }
+
+  visitType(type)
+  return types
+}
+
+const resolveUnionTypes = (
+  checker: ts.TypeChecker,
+  type: ts.Type
+): { types: ts.Type[]; names: string[] } => {
+  const types: ts.Type[] = []
+  const names: string[] = []
+
+  // Check if it's a union type AND not part of an intersection
+  if (type.isUnion() && !(type.flags & ts.TypeFlags.Intersection)) {
+    for (const t of type.types) {
+      const name = nullifyTypes(checker.typeToString(t))
+      if (name) {
+        types.push(t)
+        names.push(name)
+      }
+    }
+  } else {
+    const name = nullifyTypes(checker.typeToString(type))
+    if (name) {
+      types.push(type)
+      names.push(name)
+    }
+  }
+
+  return { types, names }
+}
+
+const getNamesAndTypes = (
+  checker: ts.TypeChecker,
+  typesMap: TypesMap,
+  direction: 'Input' | 'Output',
+  funcName: string,
+  type?: ts.Type
+) => {
+  if (!type) {
+    return { names: [], types: [] }
+  }
+
+  // 1) Handle an explicit void (or undefined) type up front
+  if (type.flags & ts.TypeFlags.VoidLike) {
+    return {
+      names: ['void'],
+      types: [type],
+    }
+  }
+
+  // 2) For unions, resolve all member names/types
+  const { names: rawNames, types: rawTypes } = resolveUnionTypes(checker, type)
+
+  // If the union is exactly [void], we'd have caught it above.
+  // If it's e.g. [string, void], rawNames should already include 'void'.
+
+  // 3) If multiple names or the single name isn't a valid identifier,
+  //    we emit an alias type.
+  const firstName = rawNames[0]
+  if (rawNames.length > 1 || (firstName && !isValidVariableName(firstName))) {
+    const aliasType = rawNames.join(' | ')
+    const aliasName =
+      funcName.charAt(0).toUpperCase() + funcName.slice(1) + direction
+
+    // record the alias in your TypesMap
+    const references = rawTypes
+      .map((t) => resolveTypeImports(t, typesMap, true))
+      .flat()
+
+    typesMap.addCustomType(aliasName, aliasType, references)
+
+    return {
+      names: [aliasName],
+      types: rawTypes,
+    }
+  }
+
+  // 4) Single, valid name → inline it
+  const uniqueNames = rawNames
+    .map((name, i) => {
+      const t = rawTypes[i]
+      if (!t) {
+        throw new Error(`Expected type for name "${name}" in ${funcName}`)
+      }
+      if (isPrimitiveType(t)) {
+        return name
+      }
+      // non-primitive: import/alias it inline
+      return resolveTypeImports(t, typesMap, false)
+    })
+    .flat()
+
+  return {
+    names: uniqueNames,
+    types: rawTypes,
+  }
+}
+
+const isPrimitiveType = (type: ts.Type): boolean => {
+  const primitiveFlags =
+    ts.TypeFlags.Number |
+    ts.TypeFlags.String |
+    ts.TypeFlags.Boolean |
+    ts.TypeFlags.BigInt |
+    ts.TypeFlags.ESSymbol |
+    ts.TypeFlags.Void |
+    ts.TypeFlags.Undefined |
+    ts.TypeFlags.Null |
+    ts.TypeFlags.Any |
+    ts.TypeFlags.Unknown |
+    ts.TypeFlags.VoidLike
+
+  return (type.flags & primitiveFlags) !== 0
+}
+
+/**
+ * If `type` is a `Promise<T>`, return `T`, otherwise return `type` itself.
+ */
+function unwrapPromise(checker: ts.TypeChecker, type: ts.Type): ts.Type {
+  if (!type?.symbol) return type
+
+  const isPromise =
+    type.symbol.name === 'Promise' &&
+    checker.getFullyQualifiedName(type.symbol).includes('Promise')
+
+  // aliasTypeArguments covers most Promise<T> cases
+  if (isPromise && type.aliasTypeArguments?.length === 1) {
+    return type.aliasTypeArguments[0]!
+  }
+
+  // fallback for raw TypeReference
+  if (isPromise && (type as ts.TypeReference).typeArguments?.length === 1) {
+    return (type as ts.TypeReference).typeArguments![0]!
+  }
+
+  return type
+}
+
+/**
+ * Inspect pikkuFunc calls, extract input/output and first-arg destructuring,
+ * then push into state.functions.meta.
+ */
+export function addFunctions(
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters
+) {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args, typeArguments } = node
+
+  // only handle calls like pikkuFunc(...)
+  if (!ts.isIdentifier(expression)) {
+    return
+  }
+
+  // Match identifiers that contain both "pikku" and "func" (case insensitive)
+  const pikkuFuncPattern = /pikku.*func/i
+  if (!pikkuFuncPattern.test(expression.text)) {
+    return
+  }
+
+  // only handle calls like pikkuFunc(...)
+  if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
+    return
+  }
+
+  if (args.length === 0) return
+
+  const { pikkuFuncName, name } = extractFunctionName(node, checker)
+
+  // determine the actual handler expression:
+  // either the `func` prop or the first argument directly
+  let handlerNode: ts.Expression = args[0]!
+  if (ts.isObjectLiteralExpression(handlerNode)) {
+    const fnProp = getPropertyAssignmentInitializer(
+      handlerNode,
+      'func',
+      true,
+      checker
+    )
+    if (
+      !fnProp ||
+      (!ts.isArrowFunction(fnProp) && !ts.isFunctionExpression(fnProp))
+    ) {
+      console.error(`• No valid 'func' property found for ${pikkuFuncName}.`)
+      return
+    }
+    handlerNode = fnProp
+  }
+
+  if (
+    !ts.isArrowFunction(handlerNode) &&
+    !ts.isFunctionExpression(handlerNode)
+  ) {
+    console.error(`• Handler for ${name} is not a function.`)
+    return
+  }
+
+  const services: FunctionServicesMeta = {
+    optimized: true,
+    services: [],
+  }
+
+  const firstParam = handlerNode.parameters[0]
+  if (firstParam) {
+    if (ts.isObjectBindingPattern(firstParam.name)) {
+      for (const elem of firstParam.name.elements) {
+        const original =
+          elem.propertyName && ts.isIdentifier(elem.propertyName)
+            ? elem.propertyName.text
+            : ts.isIdentifier(elem.name)
+              ? elem.name.text
+              : undefined
+        if (original) {
+          services.services.push(original)
+        }
+      }
+    } else if (
+      ts.isIdentifier(firstParam.name) &&
+      !firstParam.name.text.startsWith('_')
+    ) {
+      services.optimized = false
+    }
+  }
+
+  // --- Generics → ts.Type[], unwrapped from Promise ---
+  const genericTypes: ts.Type[] = (typeArguments ?? [])
+    .map((tn) => checker.getTypeFromTypeNode(tn))
+    .map((t) => unwrapPromise(checker, t))
+
+  // --- Input Extraction ---
+  let { names: inputNames, types: inputTypes } = getNamesAndTypes(
+    checker,
+    state.functions.typesMap,
+    'Input',
+    name,
+    genericTypes[0]
+  )
+  if (inputTypes.length === 0) {
+    console.warn(
+      `\x1b[31m• Unknown input type for '${name}', assuming void.\x1b[0m`
+    )
+  }
+
+  // --- Output Extraction ---
+  let outputNames: string[] = []
+  if (genericTypes.length >= 2) {
+    outputNames = getNamesAndTypes(
+      checker,
+      state.functions.typesMap,
+      'Output',
+      name,
+      genericTypes[1]
+    ).names
+  } else {
+    const sig = checker.getSignatureFromDeclaration(handlerNode)
+    if (sig) {
+      const rawRet = checker.getReturnTypeOfSignature(sig)
+      const unwrapped = unwrapPromise(checker, rawRet)
+      outputNames = getNamesAndTypes(
+        checker,
+        state.functions.typesMap,
+        'Output',
+        pikkuFuncName,
+        unwrapped
+      ).names
+    }
+  }
+
+  // --- Record metadata ---
+  state.functions.files.add(node.getSourceFile().fileName)
+
+  if (inputNames.length > 1) {
+    console.warn(
+      'More than one input type detected, only the first one will be used as a schema.'
+    )
+  }
+
+  state.functions.meta[pikkuFuncName] = {
+    pikkuFuncName,
+    name,
+    services,
+    schemaName: inputNames[0] ?? null,
+    inputs: inputNames.filter((n) => n !== 'void') ?? null,
+    outputs: outputNames.filter((n) => n !== 'void') ?? null,
+  }
+}

package/src/add-http-route.ts

@@ -0,0 +1,123 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { pathToRegexp } from 'path-to-regexp'
+import { HTTPMethod } from '@pikku/core/http'
+import { APIDocs } from '@pikku/core'
+import {
+  extractFunctionName,
+  getPropertyAssignmentInitializer,
+  matchesFilters,
+} from './utils.js'
+import { InspectorState, InspectorFilters } from './types.js'
+
+/**
+ * Populate metaInputTypes for a given route based on method, input type,
+ * query and params. Returns undefined (we only mutate metaTypes).
+ */
+export const getInputTypes = (
+  metaTypes: Map<
+    string,
+    { query?: string[]; params?: string[]; body?: string[] }
+  >,
+  methodType: string,
+  inputType: string | null,
+  queryValues: string[],
+  paramsValues: string[]
+): undefined => {
+  if (!inputType) return
+  metaTypes.set(inputType, {
+    query: queryValues,
+    params: paramsValues,
+    body: ['post', 'put', 'patch'].includes(methodType)
+      ? [...new Set([...queryValues, ...paramsValues])]
+      : [],
+  })
+  return
+}
+
+/**
+ * Simplified addHTTPRoute: re-uses function metadata from state.functions.meta
+ * instead of re-inferring types here.
+ */
+export const addHTTPRoute = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters
+) => {
+  // only look at calls
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+  if (!ts.isIdentifier(expression) || expression.text !== 'addHTTPRoute') return
+
+  // must pass an object literal
+  const firstArg = args[0]
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+  const obj = firstArg
+
+  // --- extract HTTP metadata ---
+  const route = getPropertyValue(obj, 'route') as string | null
+  if (!route) return
+
+  const keys = pathToRegexp(route).keys
+  const params = keys.filter((k) => k.type === 'param').map((k) => k.name)
+
+  const method =
+    (getPropertyValue(obj, 'method') as string)?.toLowerCase() || 'get'
+  const docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
+  const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+  const query = (getPropertyValue(obj, 'query') as string[]) || []
+
+  if (!matchesFilters(filters, { tags }, { type: 'http', name: route })) {
+    return
+  }
+
+  // --- find the referenced function ---
+  const funcInitializer = getPropertyAssignmentInitializer(
+    obj,
+    'func',
+    true,
+    checker
+  )
+  if (!funcInitializer) {
+    console.error(`• No valid 'func' property for route '${route}'.`)
+    return
+  }
+
+  const funcName = extractFunctionName(funcInitializer, checker).pikkuFuncName
+
+  // lookup existing function metadata
+  const fnMeta = state.functions.meta[funcName]
+  if (!fnMeta) {
+    console.log(Object.keys(state.functions.meta))
+    console.error(`• No function metadata found for '${funcName}'.`)
+    return
+  }
+  const input = fnMeta.inputs?.[0] || null
+  const output = fnMeta.outputs?.[0] || null
+
+  // --- compute inputTypes (body/query/params) ---
+  const inputTypes = getInputTypes(
+    state.http.metaInputTypes,
+    method,
+    input,
+    query,
+    params
+  )
+
+  // --- record route ---
+  state.http.files.add(node.getSourceFile().fileName)
+  state.http.meta.push({
+    pikkuFuncName: funcName,
+    route,
+    method: method as HTTPMethod,
+    input,
+    output,
+    params: params.length > 0 ? params : undefined,
+    query: query.length > 0 ? query : undefined,
+    inputTypes,
+    docs,
+    tags,
+  })
+}

package/src/add-schedule.ts

@@ -0,0 +1,76 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { APIDocs } from '@pikku/core'
+import { InspectorFilters, InspectorState } from './types.js'
+import { extractFunctionName, matchesFilters } from './utils.js'
+
+export const addSchedule = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  filters: InspectorFilters
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addScheduledTask
+  if (!ts.isIdentifier(expression) || expression.text !== 'addScheduledTask') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const nameValue = getPropertyValue(obj, 'name') as string | null
+    const scheduleValue = getPropertyValue(obj, 'schedule') as string | null
+    const docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
+    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+
+    // --- find the referenced function ---
+    const funcProp = obj.properties.find(
+      (p) =>
+        ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'func'
+    ) as ts.PropertyAssignment | undefined
+
+    if (!funcProp || !ts.isIdentifier(funcProp.initializer)) {
+      console.error(
+        `• No valid 'func' property for scheduled task '${nameValue}'.`
+      )
+      return
+    }
+    const pikkuFuncName = extractFunctionName(
+      funcProp.initializer,
+      checker
+    ).pikkuFuncName
+
+    if (!nameValue || !scheduleValue) {
+      return
+    }
+
+    if (
+      !matchesFilters(filters, { tags }, { type: 'schedule', name: nameValue })
+    ) {
+      return
+    }
+
+    state.scheduledTasks.files.add(node.getSourceFile().fileName)
+    state.scheduledTasks.meta[nameValue] = {
+      pikkuFuncName,
+      name: nameValue,
+      schedule: scheduleValue,
+      docs,
+      tags,
+    }
+  }
+}

package/src/does-type-extend-core-type.ts

@@ -0,0 +1,53 @@
+import * as ts from 'typescript'
+
+export const doesTypeExtendsCore = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  visitedTypes: Set<ts.Type>,
+  coreType: string
+): boolean => {
+  if (!type || !checker) return false
+
+  // Avoid infinite recursion by checking if we've already visited this type
+  if (visitedTypes.has(type)) {
+    return false
+  }
+  visitedTypes.add(type)
+
+  const typeSymbol = type.getSymbol()
+  if (typeSymbol) {
+    // Check if the type is the core type
+    if (typeSymbol.getName() === coreType) {
+      return true
+    }
+
+    // For interface and class types, check their base types
+    if (type.isClassOrInterface()) {
+      const baseTypes = type.getBaseTypes() || []
+      for (const baseType of baseTypes) {
+        if (doesTypeExtendsCore(baseType, checker, visitedTypes, coreType)) {
+          return true
+        }
+      }
+    }
+  }
+
+  // For type aliases, get the aliased type
+  if (type.aliasSymbol) {
+    const aliasedType = checker.getDeclaredTypeOfSymbol(type.aliasSymbol)
+    if (doesTypeExtendsCore(aliasedType, checker, visitedTypes, coreType)) {
+      return true
+    }
+  }
+
+  // For union and intersection types, check all constituent types
+  if (type.isUnionOrIntersection()) {
+    for (const subType of type.types) {
+      if (doesTypeExtendsCore(subType, checker, visitedTypes, coreType)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}

package/src/get-property-value.ts

@@ -0,0 +1,84 @@
+import { APIDocs } from '@pikku/core'
+import * as ts from 'typescript'
+
+export const getPropertyValue = (
+  obj: ts.ObjectLiteralExpression,
+  propertyName: string
+): string | string[] | null | APIDocs => {
+  const property = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === propertyName
+  )
+
+  if (property && ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer
+
+    // Special handling for 'query' -> expect an array of strings
+    if (
+      ['query', 'tags'].includes(propertyName) &&
+      ts.isArrayLiteralExpression(initializer)
+    ) {
+      const stringArray = initializer.elements
+        .map((element) => {
+          if (ts.isStringLiteral(element)) {
+            return element.text
+          }
+          return null
+        })
+        .filter((item) => item !== null) as string[] // Filter non-null and assert type
+
+      return stringArray.length > 0 ? stringArray : null
+    }
+
+    // Special handling for 'docs' -> expect RouteDocs
+    if (propertyName === 'docs' && ts.isObjectLiteralExpression(initializer)) {
+      const docs: APIDocs = {}
+
+      initializer.properties.forEach((prop) => {
+        if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+          const propName = prop.name.text
+
+          if (propName === 'summary' && ts.isStringLiteral(prop.initializer)) {
+            docs.summary = prop.initializer.text
+          } else if (
+            propName === 'description' &&
+            ts.isStringLiteral(prop.initializer)
+          ) {
+            docs.description = prop.initializer.text
+          } else if (
+            propName === 'tags' &&
+            ts.isArrayLiteralExpression(prop.initializer)
+          ) {
+            docs.tags = prop.initializer.elements
+              .filter(ts.isStringLiteral)
+              .map((element) => element.text)
+          } else if (
+            propName === 'errors' &&
+            ts.isArrayLiteralExpression(prop.initializer)
+          ) {
+            docs.errors = prop.initializer.elements
+              .filter(ts.isIdentifier)
+              .map((element) => element.text as unknown as string)
+          }
+        }
+      })
+
+      return docs
+    }
+
+    // Handle string literals for other properties
+    if (
+      ts.isStringLiteral(initializer) ||
+      ts.isNoSubstitutionTemplateLiteral(initializer)
+    ) {
+      return initializer.text
+    } else {
+      // Handle other initializer types if necessary
+      return initializer.getText()
+    }
+  }
+
+  return null
+}