@pikku/inspector 0.6.2

package/src/add-channel.ts

@@ -0,0 +1,168 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { pathToRegexp } from 'path-to-regexp'
+import { APIDocs } from '@pikku/core'
+import { getInputTypes } from './add-route.js'
+import { getPropertyAssignment, getFunctionTypes } from './utils.js'
+import { ChannelMeta } from '@pikku/core/channel'
+import { TypesMap } from './types-map.js'
+import { InspectorState } from './types.js'
+
+const addMessagesRoutes = (
+  obj: ts.ObjectLiteralExpression,
+  checker: ts.TypeChecker,
+  typesMap: TypesMap
+) => {
+  const messageTypes: ChannelMeta['messageRoutes'] = {}
+
+  // Find the onMessageRoute property
+  const messagesProperty = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === 'onMessageRoute'
+  )
+
+  if (!messagesProperty || !ts.isPropertyAssignment(messagesProperty)) {
+    console.log(
+      'onMessageRoute property not found or is not a valid assignment.'
+    )
+    return {}
+  }
+
+  const initializer = messagesProperty.initializer
+  // Ensure initializer is an object literal expression
+  if (!ts.isObjectLiteralExpression(initializer)) {
+    console.log('onMessageRoute is not an object literal.')
+    return {}
+  }
+
+  // Iterate over the first level properties (like 'event')
+  initializer.properties.forEach((property) => {
+    const channel = property.name!.getText()
+    messageTypes[channel] = {}
+
+    if (ts.isPropertyAssignment(property)) {
+      const nestedObject = property.initializer
+      if (ts.isObjectLiteralExpression(nestedObject)) {
+        const keys = nestedObject.properties.map((p) => p.name?.getText())
+        for (const route of keys) {
+          if (route) {
+            const result = getFunctionTypes(checker, nestedObject, {
+              funcName: route,
+              inputIndex: 0,
+              outputIndex: 1,
+              typesMap,
+            })
+            const inputs = result?.inputs || null
+            const outputs = result?.outputs || null
+            messageTypes[channel][route] = { inputs, outputs }
+          }
+        }
+      } else {
+        console.warn('Nested property is not an object literal:', nestedObject)
+      }
+    } else {
+      console.warn(
+        `Property "${property.getText()}" is a ${ts.SyntaxKind[property.kind]}`
+      )
+    }
+  })
+
+  return messageTypes
+}
+
+export const addChannel = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addRoute
+  if (!ts.isIdentifier(expression) || expression.text !== 'addChannel') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  let docs: APIDocs | undefined
+  let paramsValues: string[] | null = []
+  let queryValues: string[] | [] = []
+  let inputType: string | null = null
+  let route: string | null = null
+  let name: string | null = null
+
+  state.channels.files.add(node.getSourceFile().fileName)
+
+  // Check if the first argument is an object literal
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    name = getPropertyValue(obj, 'name') as string | null
+    route = getPropertyValue(obj, 'route') as string | null
+
+    if (!name) {
+      console.error('Channel name is required')
+      return
+    }
+
+    if (route) {
+      const { keys } = pathToRegexp(route)
+      paramsValues = keys.reduce((result, { type, name }) => {
+        if (type === 'param') {
+          result.push(name)
+        }
+        return result
+      }, [] as string[])
+    } else {
+      route = ''
+    }
+
+    docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
+    queryValues = (getPropertyValue(obj, 'query') as string[]) || []
+
+    const connect = !!getPropertyAssignment(obj, 'onConnect')
+    const disconnect = !!getPropertyAssignment(obj, 'onDisconnect')
+    const { inputs, outputs } = getFunctionTypes(checker, obj, {
+      funcName: 'onMessage',
+      inputIndex: 0,
+      outputIndex: 1,
+      typesMap: state.channels.typesMap,
+    })
+    const message = { inputs, outputs }
+    const messageRoutes = addMessagesRoutes(
+      obj,
+      checker,
+      state.channels.typesMap
+    )
+
+    state.channels.meta.push({
+      name,
+      route,
+      input: inputType,
+      params: paramsValues.length > 0 ? paramsValues : undefined,
+      query: queryValues.length > 0 ? queryValues : undefined,
+      inputTypes: getInputTypes(
+        state.channels.metaInputTypes,
+        'get',
+        inputType,
+        queryValues,
+        paramsValues
+      ),
+      connect,
+      disconnect,
+      message,
+      messageRoutes,
+      docs,
+    })
+  }
+}

package/src/add-file-extends-core-type.ts

@@ -0,0 +1,50 @@
+import * as ts from 'typescript'
+import { PathToNameAndType } from './types.js'
+
+// const VRAMEWORK_TYPES = ['CoreConfig', 'CoreService', 'CoreServices', 'CoreSingletonService', 'CoreSessionService']
+
+export const addFileExtendsCoreType = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  methods: PathToNameAndType,
+  expectedTypeName: string
+) => {
+  if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
+    const fileName = node.getSourceFile().fileName
+    const typeName = node.name?.getText()
+
+    // Check if the class or interface extends the expected type
+    if (node.heritageClauses) {
+      for (const clause of node.heritageClauses) {
+        if (clause.token === ts.SyntaxKind.ExtendsKeyword) {
+          for (const type of clause.types) {
+            const extendedTypeName = type.expression.getText()
+            let extendedTypeDeclarationPath: string | null = null
+
+            // Check if the extended type matches the expected type name
+            if (extendedTypeName === expectedTypeName) {
+              // Retrieve the symbol of the extended type
+              const typeSymbol = checker.getSymbolAtLocation(type.expression)
+              const declaration =
+                typeSymbol &&
+                typeSymbol.declarations &&
+                typeSymbol.declarations[0]
+              if (declaration) {
+                const sourceFile = declaration.getSourceFile()
+                extendedTypeDeclarationPath = sourceFile.fileName // Get the path of the file where the extended type was declared
+              }
+
+              const variables = methods[fileName] || []
+              variables.push({
+                variable: undefined,
+                type: typeName,
+                typePath: extendedTypeDeclarationPath,
+              })
+              methods[fileName] = variables
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+import * as ts from 'typescript'
+import { doesTypeExtendsCore } from './does-type-extend-core-type.js'
+import { PathToNameAndType } from './types.js'
+
+export const addFileWithConfig = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  configs: PathToNameAndType
+) => {
+  if (ts.isVariableDeclaration(node)) {
+    const fileName = node.getSourceFile().fileName
+    const variableSymbol = checker.getSymbolAtLocation(node.name)
+
+    if (variableSymbol) {
+      const variableType = checker.getTypeOfSymbolAtLocation(
+        variableSymbol,
+        node.name
+      )
+      const variableName = node.name.getText()
+      const variableTypeText = node.type?.getText()
+
+      // Check if the type extends CoreConfig
+      if (doesTypeExtendsCore(variableType, checker, new Set(), 'CoreConfig')) {
+        // Retrieve the symbol of the type (if it has one)
+        const typeSymbol = variableType.symbol
+        let typeDeclarationPath: string | null = null
+        const declaration =
+          typeSymbol && typeSymbol.declarations && typeSymbol.declarations[0]
+
+        if (declaration) {
+          const sourceFile = declaration.getSourceFile()
+          typeDeclarationPath = sourceFile.fileName // Get the path of the file where the type was declared
+        }
+
+        const variables = configs[fileName] || []
+        variables.push({
+          variable: variableName,
+          type: variableTypeText || null,
+          typePath: typeDeclarationPath,
+        })
+        configs[fileName] = variables
+      }
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+import * as ts from 'typescript'
+import { PathToNameAndType } from './types.js'
+
+export const addFileWithFactory = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  methods: PathToNameAndType = new Map(),
+  expectedTypeName: string
+) => {
+  if (ts.isVariableDeclaration(node)) {
+    const fileName = node.getSourceFile().fileName
+    const variableTypeNode = node.type
+    const variableName = node.name.getText()
+
+    if (variableTypeNode && ts.isTypeReferenceNode(variableTypeNode)) {
+      const typeNameNode = variableTypeNode.typeName || null
+
+      let typeDeclarationPath: string | null = null
+
+      // Check if the type name matches the expected type name
+      if (
+        ts.isIdentifier(typeNameNode) &&
+        typeNameNode.text === expectedTypeName
+      ) {
+        const typeSymbol = checker.getSymbolAtLocation(typeNameNode)
+        const declaration =
+          typeSymbol && typeSymbol.declarations && typeSymbol.declarations[0]
+        if (declaration) {
+          const sourceFile = declaration.getSourceFile()
+          typeDeclarationPath = sourceFile.fileName // Get the path of the file where the type was declared
+        }
+
+        const variables = methods[fileName] || []
+        variables.push({
+          variable: variableName,
+          type: typeNameNode.getText(),
+          typePath: typeDeclarationPath,
+        })
+        methods[fileName] = variables
+      }
+
+      // Handle qualified type names if necessary
+      else if (ts.isQualifiedName(typeNameNode)) {
+        const lastName = typeNameNode.right.text
+        if (lastName === expectedTypeName) {
+          const typeSymbol = checker.getSymbolAtLocation(typeNameNode.right)
+          const declaration =
+            typeSymbol && typeSymbol.declarations && typeSymbol.declarations[0]
+          if (declaration) {
+            const sourceFile = declaration.getSourceFile()
+            typeDeclarationPath = sourceFile.fileName // Get the path of the file where the type was declared
+          }
+
+          const variables = methods[fileName] || []
+          variables.push({
+            variable: variableName,
+            type: typeNameNode.getText(),
+            typePath: typeDeclarationPath,
+          })
+          methods[fileName] = variables
+        }
+      }
+    }
+  }
+}

package/src/add-route.ts

@@ -0,0 +1,131 @@
+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 { extractTypeKeys, getFunctionTypes } from './utils.js'
+import { MetaInputTypes, InspectorState } from './types.js'
+
+export const getInputTypes = (
+  metaTypes: MetaInputTypes,
+  methodType: string,
+  inputType: string | null,
+  queryValues: string[],
+  paramsValues: string[]
+) => {
+  if (!inputType) {
+    return undefined
+  }
+
+  if (inputType) {
+    metaTypes.set(inputType, {
+      query: queryValues,
+      params: paramsValues,
+      body: ['post', 'put', 'patch'].includes(methodType)
+        ? [...new Set([...queryValues, ...paramsValues])]
+        : [],
+    })
+  }
+
+  return undefined
+}
+
+export const addRoute = (
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addRoute
+  if (!ts.isIdentifier(expression) || expression.text !== 'addRoute') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  let docs: APIDocs | undefined
+  let methodValue: string | null = null
+  let paramsValues: string[] | null = []
+  let queryValues: string[] | [] = []
+  let routeValue: string | null = null
+
+  state.http.files.add(node.getSourceFile().fileName)
+
+  // Check if the first argument is an object literal
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    routeValue = getPropertyValue(obj, 'route') as string | null
+    if (routeValue) {
+      const { keys } = pathToRegexp(routeValue)
+      paramsValues = keys.reduce((result, { type, name }) => {
+        if (type === 'param') {
+          result.push(name)
+        }
+        return result
+      }, [] as string[])
+    }
+
+    docs = (getPropertyValue(obj, 'docs') as APIDocs) || undefined
+    methodValue = getPropertyValue(obj, 'method') as string
+    queryValues = (getPropertyValue(obj, 'query') as string[]) || []
+
+    let { inputs, outputs, inputTypes } = getFunctionTypes(checker, obj, {
+      funcName: 'func',
+      inputIndex: 0,
+      outputIndex: 1,
+      typesMap: state.http.typesMap,
+    })
+
+    const input = inputs ? inputs[0] || null : null
+    const output = outputs ? outputs[0] || null : null
+
+    if (inputs && inputs?.length > 1) {
+      console.error(
+        `Only one input type is currently allowed for method '${methodValue}' and route '${routeValue}': \n\t${inputs.join('\n\t')}`
+      )
+    }
+
+    if (outputs && outputs?.length > 1) {
+      console.error(
+        `Only one output type is currently allowed for method '${methodValue}' and route '${routeValue}': \n\t${outputs.join('\n\t')}`
+      )
+    }
+
+    if (inputTypes[0] && !['post', 'put', 'patch'].includes(methodValue)) {
+      queryValues = [
+        ...new Set([...queryValues, ...extractTypeKeys(inputTypes[0])]),
+      ].filter((query) => !paramsValues?.includes(query))
+    }
+
+    if (!routeValue) {
+      return
+    }
+
+    state.http.meta.push({
+      route: routeValue!,
+      method: methodValue! as HTTPMethod,
+      input,
+      output,
+      params: paramsValues.length > 0 ? paramsValues : undefined,
+      query: queryValues.length > 0 ? queryValues : undefined,
+      inputTypes: getInputTypes(
+        state.http.metaInputTypes,
+        methodValue,
+        input,
+        queryValues,
+        paramsValues
+      ),
+      docs,
+    })
+  }
+}

package/src/add-schedule.ts

@@ -0,0 +1,47 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from './get-property-value.js'
+import { APIDocs } from '@pikku/core'
+import { InspectorState } from './types.js'
+
+export const addSchedule = (
+  node: ts.Node,
+  _checker: ts.TypeChecker,
+  state: InspectorState
+) => {
+  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
+  }
+
+  state.scheduledTasks.files.add(node.getSourceFile().fileName)
+
+  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
+
+    if (!nameValue || !scheduleValue) {
+      return
+    }
+
+    state.scheduledTasks.meta.push({
+      name: nameValue,
+      schedule: scheduleValue,
+      docs,
+    })
+  }
+}

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,81 @@
+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 (propertyName === 'query' && 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
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { inspect } from './inspector.js'
+export type { TypesMap } from './types-map.js'
+export type * from './types.js'
+export type { InspectorState } from './types.js'

package/src/inspector.ts

@@ -0,0 +1,53 @@
+import * as ts from 'typescript'
+import { visit } from './visit.js'
+import { TypesMap } from './types-map.js'
+import { InspectorState, InspectorHTTPState } from './types.js'
+
+export const normalizeHTTPTypes = (
+  httpState: InspectorHTTPState
+): InspectorHTTPState => {
+  return httpState
+}
+
+export const inspect = (routeFiles: string[]): InspectorState => {
+  const program = ts.createProgram(routeFiles, {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.CommonJS,
+  })
+  const checker = program.getTypeChecker()
+  const sourceFiles = program.getSourceFiles()
+
+  const state: InspectorState = {
+    sessionServicesTypeImportMap: new Map(),
+    userSessionTypeImportMap: new Map(),
+    singletonServicesFactories: new Map(),
+    sessionServicesFactories: new Map(),
+    configFactories: new Map(),
+    http: {
+      typesMap: new TypesMap(),
+      metaInputTypes: new Map(),
+      meta: [],
+      files: new Set(),
+    },
+    channels: {
+      typesMap: new TypesMap(),
+      metaInputTypes: new Map(),
+      files: new Set(),
+      meta: [],
+    },
+    scheduledTasks: {
+      meta: [],
+      files: new Set(),
+    },
+  }
+
+  for (const sourceFile of sourceFiles) {
+    ts.forEachChild(sourceFile, (child) => visit(checker, child, state))
+  }
+
+  // Normalise the typesMap
+
+  state.http = normalizeHTTPTypes(state.http)
+
+  return state
+}