@pikku/inspector 0.12.63 → 0.12.65

package/src/utils/post-process.test.ts

@@ -12,9 +12,11 @@ import {
   validateRemoteAddonAuth,
   validateAgentToolReferences,
   validateAgentModels,
+  validateSchemaReferences,
 } from './post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorState, InspectorLogger } from '../types.js'
+import { TypesMap } from '../types-map.js'
 
 const makeCriticalLogger = () => {
   const criticals: { code: string; message: string }[] = []
@@ -928,3 +930,123 @@ describe('validateAgentModels (aliases resolve against pikku.config.json)', () =
     })
   }
 })
+
+const makeDiagnosticLogger = () => {
+  const diagnostics: { code: string; severity: string; message: string }[] = []
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: () => {},
+    diagnostic: (d: any) =>
+      diagnostics.push({
+        code: String(d.code),
+        severity: d.severity,
+        message: d.message,
+      }),
+  } as unknown as InspectorLogger
+  return { logger, diagnostics }
+}
+
+const makeSchemaRefState = (
+  meta: Record<string, { inputs?: string[]; outputs?: string[] }>,
+  schemas: string[],
+  types: Record<string, string> = {}
+): InspectorState => {
+  const typesMap = new TypesMap()
+  for (const [name, path] of Object.entries(types)) {
+    typesMap.addType(name, path)
+  }
+  return {
+    functions: { meta, typesMap },
+    schemas: Object.fromEntries(schemas.map((name) => [name, {}])),
+  } as unknown as InspectorState
+}
+
+describe('validateSchemaReferences', () => {
+  test('an output type that was never exported is reported, not silent', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    validateSchemaReferences(
+      logger,
+      makeSchemaRefState(
+        { getStructure: { outputs: ['StructureSummary'] } },
+        []
+      )
+    )
+    assert.equal(diagnostics.length, 1)
+    assert.equal(diagnostics[0]!.code, ErrorCode.SCHEMA_REFERENCE_UNRESOLVED)
+    assert.equal(diagnostics[0]!.severity, 'error')
+    assert.match(
+      diagnostics[0]!.message,
+      /getStructure\.output → 'StructureSummary'/
+    )
+    assert.match(diagnostics[0]!.message, /declared but not exported/)
+  })
+
+  test('an unresolved input is reported the same way', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    validateSchemaReferences(
+      logger,
+      makeSchemaRefState({ getStructure: { inputs: ['StructureQuery'] } }, [])
+    )
+    assert.equal(diagnostics.length, 1)
+    assert.match(
+      diagnostics[0]!.message,
+      /getStructure\.input → 'StructureQuery'/
+    )
+  })
+
+  test('a generated schema resolves and says nothing', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    validateSchemaReferences(
+      logger,
+      makeSchemaRefState({ getStructure: { outputs: ['StructureSummary'] } }, [
+        'StructureSummary',
+      ])
+    )
+    assert.deepEqual(diagnostics, [])
+  })
+
+  test('primitive contracts are never schema references', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    validateSchemaReferences(
+      logger,
+      makeSchemaRefState(
+        { getStructure: { inputs: ['string'], outputs: ['void'] } },
+        []
+      )
+    )
+    assert.deepEqual(diagnostics, [])
+  })
+
+  test('a name shared by two files is reported under the disambiguated name', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    const typesMap = new TypesMap()
+    const mine = typesMap.addUniqueType('StructureSummary', '/structure.ts')
+    typesMap.addUniqueType('StructureSummary', '/other-structure.ts')
+    const state = {
+      functions: { meta: { getStructure: { outputs: [mine] } }, typesMap },
+      schemas: {},
+    } as unknown as InspectorState
+    validateSchemaReferences(logger, state)
+    assert.equal(diagnostics.length, 1)
+    assert.match(diagnostics[0]!.message, new RegExp(`→ '${mine}'`))
+  })
+
+  test('every unresolved contract is named in one diagnostic, not one each', () => {
+    const { logger, diagnostics } = makeDiagnosticLogger()
+    validateSchemaReferences(
+      logger,
+      makeSchemaRefState(
+        {
+          getStructure: { outputs: ['StructureSummary'] },
+          listStructures: { outputs: ['StructureSummary'] },
+        },
+        []
+      )
+    )
+    assert.equal(diagnostics.length, 1)
+    assert.match(diagnostics[0]!.message, /2 function contracts name a schema/)
+  })
+})

package/src/utils/post-process.ts

@@ -17,6 +17,7 @@ import { join } from 'node:path'
 import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
 import { findSecretAliasServices } from './secret-alias-services.js'
+import { resolveCoreType } from './resolve-core-type.js'
 import { relative } from 'node:path'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
 import { flattenScopeDefinitions } from '@pikku/core/scope'
@@ -106,19 +107,25 @@ function extractAllServices(
   }
 
   // Extract all singleton services from the SingletonServices type
-  const singletonServicesTypes = state.typesLookup.get('SingletonServices')
-  if (singletonServicesTypes && singletonServicesTypes.length > 0) {
-    const singletonServiceNames = extractTypeKeys(singletonServicesTypes[0])
-    state.serviceAggregation.allSingletonServices = singletonServiceNames.sort()
+  const singletonServicesType = resolveCoreType(
+    state.typesLookup,
+    state.singletonServicesTypeImportMap
+  )
+  if (singletonServicesType) {
+    state.serviceAggregation.allSingletonServices = extractTypeKeys(
+      singletonServicesType
+    ).sort()
   }
 
   // Extract all services from the Services type
-  const servicesTypes = state.typesLookup.get('Services')
-  if (servicesTypes && servicesTypes.length > 0) {
-    const allServiceNames = extractTypeKeys(servicesTypes[0])
+  const servicesType = resolveCoreType(
+    state.typesLookup,
+    state.wireServicesTypeImportMap
+  )
+  if (servicesType) {
     // Wire services are those in Services but not in SingletonServices
     const singletonSet = new Set(state.serviceAggregation.allSingletonServices)
-    state.serviceAggregation.allWireServices = allServiceNames
+    state.serviceAggregation.allWireServices = extractTypeKeys(servicesType)
       .filter((name) => !singletonSet.has(name))
       .sort()
   }
@@ -1101,11 +1108,14 @@ export function validateNoSecretAliasServices(
   if (!('typesLookup' in state)) {
     return
   }
-  const singletonServicesTypes = state.typesLookup.get('SingletonServices')
-  if (!singletonServicesTypes?.length) {
+  const singletonServicesType = resolveCoreType(
+    state.typesLookup,
+    state.singletonServicesTypeImportMap
+  )
+  if (!singletonServicesType) {
     return
   }
-  const aliases = findSecretAliasServices(singletonServicesTypes[0]!, checker)
+  const aliases = findSecretAliasServices(singletonServicesType, checker)
   if (aliases.length === 0) {
     return
   }

package/src/utils/resolve-core-type.test.ts

@@ -0,0 +1,142 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import ts from 'typescript'
+import { aggregateRequiredServices } from './post-process.js'
+import type { InspectorState, PathToNameAndType } from '../types.js'
+
+const SOURCE_FILE = '/application-types.ts'
+
+/**
+ * Builds the slice of inspector state that service extraction reads: the
+ * `typesLookup` entry the AST walk records under whatever the project named its
+ * interface, and the import map that points at that name.
+ */
+const stateWithCoreTypes = (
+  source: string,
+  singletonName: string,
+  wireName: string
+): InspectorState => {
+  const host: ts.CompilerHost = {
+    ...ts.createCompilerHost({}),
+    getSourceFile: (name, languageVersion) =>
+      name === SOURCE_FILE
+        ? ts.createSourceFile(name, source, languageVersion, true)
+        : undefined,
+    fileExists: (name) => name === SOURCE_FILE,
+    readFile: (name) => (name === SOURCE_FILE ? source : undefined),
+  }
+  const program = ts.createProgram([SOURCE_FILE], { noLib: true }, host)
+  const checker = program.getTypeChecker()
+  const sourceFile = program.getSourceFile(SOURCE_FILE)!
+
+  const typesLookup = new Map<string, ts.Type[]>()
+  const importMapFor = (name: string): PathToNameAndType => {
+    const declaration = sourceFile.statements.find(
+      (statement): statement is ts.InterfaceDeclaration =>
+        ts.isInterfaceDeclaration(statement) && statement.name.text === name
+    )!
+    typesLookup.set(name, [checker.getTypeAtLocation(declaration)])
+    return new Map([
+      [SOURCE_FILE, [{ variable: name, type: name, typePath: SOURCE_FILE }]],
+    ])
+  }
+
+  return {
+    typesLookup,
+    singletonServicesTypeImportMap: importMapFor(singletonName),
+    wireServicesTypeImportMap: importMapFor(wireName),
+    serviceAggregation: {
+      requiredServices: new Set<string>(),
+      usedFunctions: new Set<string>(),
+      usedMiddleware: new Set<string>(),
+      usedPermissions: new Set<string>(),
+      allSingletonServices: [],
+      allWireServices: [],
+    },
+    functions: { meta: {} },
+    middleware: { definitions: {}, tagMiddleware: new Map() },
+    permissions: { definitions: {} },
+    http: {
+      meta: {
+        get: {},
+        post: {},
+        put: {},
+        patch: {},
+        delete: {},
+        head: {},
+        options: {},
+      },
+      routeMiddleware: new Map(),
+    },
+    channels: { meta: {} },
+    queueWorkers: { meta: {} },
+    scheduledTasks: { meta: {} },
+    mcpEndpoints: { toolsMeta: {}, promptsMeta: {}, resourcesMeta: {} },
+    agents: { agentsMeta: {} },
+    workflows: { meta: {}, graphMeta: {} },
+    wireServicesMeta: new Map(),
+    rpc: { internalMeta: {}, exposedMeta: {} },
+    scopes: { definitions: [] },
+    addonFunctions: {},
+    addonRequiredParentServices: [],
+  } as unknown as InspectorState
+}
+
+const CONVENTIONAL = `
+  interface SingletonServices { logger: string; kysely: string }
+  interface Services { logger: string; kysely: string; http: string }
+`
+
+const RENAMED = `
+  interface AppSingletonServices { logger: string; kysely: string }
+  interface AppServices { logger: string; kysely: string; http: string }
+`
+
+describe('service extraction resolves core types by declaration, not by name', () => {
+  test('the conventional names still resolve', () => {
+    const state = stateWithCoreTypes(
+      CONVENTIONAL,
+      'SingletonServices',
+      'Services'
+    )
+    aggregateRequiredServices(state)
+    assert.deepEqual(state.serviceAggregation.allSingletonServices, [
+      'kysely',
+      'logger',
+    ])
+    assert.deepEqual(state.serviceAggregation.allWireServices, ['http'])
+  })
+
+  test('a project that renamed its interfaces resolves the same way', () => {
+    const state = stateWithCoreTypes(
+      RENAMED,
+      'AppSingletonServices',
+      'AppServices'
+    )
+    aggregateRequiredServices(state)
+    assert.deepEqual(
+      state.serviceAggregation.allSingletonServices,
+      ['kysely', 'logger'],
+      'a renamed SingletonServices must not silently resolve to no services'
+    )
+    assert.deepEqual(state.serviceAggregation.allWireServices, ['http'])
+  })
+
+  test('no declaration at all leaves the lists empty for PKU724 to catch', () => {
+    const state = stateWithCoreTypes(
+      CONVENTIONAL,
+      'SingletonServices',
+      'Services'
+    )
+    state.singletonServicesTypeImportMap = new Map()
+    state.wireServicesTypeImportMap = new Map()
+    // Left at their initial empty value on purpose: `extractAllServices` only
+    // assigns when a type resolves, so seeding them here would make the
+    // assertions below true no matter what it did. `typesLookup` still holds
+    // both interfaces under their conventional names — resolving one from
+    // there is exactly the bug this guards.
+    aggregateRequiredServices(state)
+    assert.deepEqual(state.serviceAggregation.allSingletonServices, [])
+    assert.deepEqual(state.serviceAggregation.allWireServices, [])
+  })
+})

package/src/utils/resolve-core-type.ts

@@ -0,0 +1,35 @@
+import type ts from 'typescript'
+import type { PathToNameAndType } from '../types.js'
+
+/**
+ * Resolves the one interface extending a core type (`CoreConfig`,
+ * `CoreSingletonServices`, `CoreServices`) to the `ts.Type` the AST walk
+ * recorded for it.
+ *
+ * `typesLookup` is keyed by whatever the project named the interface, so
+ * reading it under a hardcoded `'SingletonServices'` only works for projects
+ * that follow the scaffold's naming. A project that renamed the interface still
+ * satisfies every required-type check and then resolves to no services at all,
+ * which surfaces far downstream as PKU724 or as every service turning optional.
+ * The import map carries the real name, so no name matching is needed.
+ *
+ * A project is only ever meant to declare one of each: `getMetaTypes` records
+ * `More than one ... found` when it sees a second, which `checkRequiredTypes`
+ * then reports. That check is the caller's to run, and extraction happens
+ * first, so where two declarations do exist this takes the first in traversal
+ * order rather than diagnosing the ambiguity itself.
+ */
+export const resolveCoreType = (
+  typesLookup: Map<string, ts.Type[]>,
+  importMap: PathToNameAndType
+): ts.Type | undefined => {
+  for (const entries of importMap.values()) {
+    for (const { type } of entries) {
+      const resolved = type ? typesLookup.get(type)?.[0] : undefined
+      if (resolved) {
+        return resolved
+      }
+    }
+  }
+  return undefined
+}