@pikku/inspector 0.12.64 → 0.12.66

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## 0.12.66
+
+### Patch Changes
+
+- 2f94a0a: Stop `pikku all` failing on a diagnostic its own codegen went on to fix.
+
+  The run inspects several times, because generating the scaffold, the leaf indexes and the type files each changes the source graph the next inspection reads. Every full inspection re-runs every validator, so the newest pass is the complete one — but the logger accumulated diagnostics across all of them, and the build gate failed the run if any pass had ever recorded a critical.
+
+  A project whose system roles grant a scaffold-declared scope (`virtualUser:*`) therefore could not build from clean: the pass taken before the scaffold existed raised PKU124, the pass taken after was clean, and the run failed anyway. Same for PKU951 on a scaffold-declared secret.
+
+  Validation diagnostics are now scoped to the pass that recorded them, so a later pass supersedes an earlier one. Diagnostics reported outside a validation pass — by a generator or a command — are untouched, and a fault every pass reports still fails the run.
+
+- 7eeff81: Record `rpc!.invoke(...)` as an invocation
+
+  `rpc` is optional on the wire, so a caller that knows it is there writes
+  `rpc!.invoke('someFunction', …)`. The inspector matched the receiver as a bare
+  identifier, but a non-null assertion is a node of its own wrapping that
+  identifier, so those call sites were never recorded.
+
+  That is silent rather than loud. An invocation is what puts a function that is
+  not `expose: true` into the runtime registry, so the target was left
+  unregistered and the dispatch failed with `Function not found` — at run time,
+  on a call site that type-checked.
+
+  The generated virtual-user scaffold dispatches exactly this way, which meant
+  `executeVirtualUserRun` was never registered: every virtual-user run sat at
+  `running` forever with nothing logged, because the scaffold's own
+  `.catch(() => {})` swallowed the rejection.
+
+  The receiver is now unwrapped through non-null assertions and parentheses
+  before it is matched.
+
+- Updated dependencies [88629af]
+- Updated dependencies [f1ccfe3]
+  - @pikku/core@0.12.96
+
+## 0.12.65
+
+### Patch Changes
+
+- b5e79c1: Resolve `Config`, `SingletonServices` and `Services` by declaration rather than
+  by name.
+
+  Service extraction read `typesLookup` under the hardcoded names the scaffold
+  happens to use, but the lookup is keyed by whatever the project named its
+  interface. A project that renamed one satisfied every required-type check and
+  then resolved to no services at all, surfacing much later as PKU724 or as every
+  singleton service turning optional. These now go through the import maps, which
+  carry the real name.
+
+  `pikku workflow` carried the same lookup as its fallback when aggregation came
+  back empty, so a project with a renamed interface was told
+  `WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED` while holding a perfectly good
+  `workflowService`.
+
+- Updated dependencies [1cc50ef]
+- Updated dependencies [a3deea4]
+- Updated dependencies [2a02288]
+  - @pikku/core@0.12.95
+
 ## 0.12.64
 
 ### Patch Changes

package/dist/add/add-cli.js

@@ -1,5 +1,6 @@
 import ts from 'typescript';
 import { extractFunctionName, makeContextBasedId, } from '../utils/extract-function-name.js';
+import { resolveCoreType } from '../utils/resolve-core-type.js';
 import { resolveMiddleware } from '../utils/middleware.js';
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js';
 import { extractWireNames } from '../utils/post-process.js';
@@ -538,8 +539,8 @@ function extractEnumFromPropertyType(type, propertyName, typeChecker) {
  */
 function extractEnumFromConfigType(logger, propertyName, typeChecker, inspectorState, _inspectorOptions) {
     // Look for Config type in typesLookup
-    const configTypes = inspectorState.typesLookup.get('Config');
-    if (!configTypes || configTypes.length === 0) {
+    const configType = resolveCoreType(inspectorState.typesLookup, inspectorState.configTypeImportMap);
+    if (!configType) {
         // Only warn once per CLI file to avoid spamming logs
         if (!configTypeWarningShown.has('missing-config-type')) {
             configTypeWarningShown.add('missing-config-type');
@@ -548,15 +549,6 @@ function extractEnumFromConfigType(logger, propertyName, typeChecker, inspectorS
         }
         return null;
     }
-    // Use the first Config type (there should only be one)
-    const configType = configTypes[0];
-    if (!configType) {
-        if (!configTypeWarningShown.has('undefined-config-type')) {
-            configTypeWarningShown.add('undefined-config-type');
-            logger.warn(`Config type is undefined in typesLookup.`);
-        }
-        return null;
-    }
     // Extract enum from the property
     return extractEnumFromPropertyType(configType, propertyName, typeChecker);
 }

package/dist/add/add-rpc-invocations.js

@@ -13,6 +13,25 @@ function outerParent(node) {
 function findCastArg(args) {
     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) {
+    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'
  */
@@ -62,10 +81,14 @@ export function addRPCInvocations(node, state, logger) {
             }
         }
         // Check for rpc.invoke('...') calls
+        const invokeReceiver = ts.isPropertyAccessExpression(expression)
+            ? invocationReceiver(expression.expression)
+            : undefined;
         if (ts.isPropertyAccessExpression(expression) &&
             expression.name.text === 'invoke' &&
-            ts.isIdentifier(expression.expression) &&
-            expression.expression.text === 'rpc') {
+            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;

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWork
 export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export type { SerializedWorkflowGraph, SerializedWorkflowGraphs, } from './utils/workflow/graph/index.js';
+export { resolveCoreType } from './utils/resolve-core-type.js';

package/dist/index.js

@@ -12,3 +12,4 @@ export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';
 export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
+export { resolveCoreType } from './utils/resolve-core-type.js';

package/dist/inspector.js

@@ -371,6 +371,10 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     state.filesAndMethodsErrors = errors;
     logger.debug(`Get files and methods completed in ${(performance.now() - startFilesAndMethods).toFixed(2)}ms`);
     if (!options.setupOnly) {
+        // Everything below re-derives from the state this pass just built, so it
+        // supersedes whatever an earlier pass concluded about a source graph the
+        // run has since finished generating into.
+        logger.beginValidationPass?.();
         const startAggregate = performance.now();
         // Apply the inspected auth handler service set before aggregation so it
         // flows into requiredServices (the generated handler's own func is opaque).
@@ -408,6 +412,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateScopeReferences(logger, state);
         validateSystemRoleScopes(logger, state);
         validatePersonaRoles(logger, state);
+        logger.endValidationPass?.();
     }
     state.program = program;
     return state;

package/dist/types.d.ts

@@ -300,6 +300,24 @@ export interface InspectorLogger {
     /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */
     critical: (code: ErrorCode, message: string) => void;
     hasCriticalErrors: () => boolean;
+    /**
+     * Opens a validation pass, discarding whatever a previous one recorded.
+     *
+     * A single `pikku all` inspects several times, because generating the
+     * scaffold, the leaf indexes and the type files each changes the source graph
+     * the next inspection reads. The validators are pure functions of that graph
+     * and every full inspection re-runs all of them, so the newest pass is always
+     * the complete one and the ones before it are strictly superseded.
+     *
+     * Without this the diagnostics accumulated instead, and a run failed on a
+     * complaint about its own half-built input: a project whose roles reference
+     * scaffold-declared scopes was reported as failing even though the pass that
+     * ran once the scaffold existed was clean. Optional so a host supplying its
+     * own logger keeps working — one that omits it simply never discards.
+     */
+    beginValidationPass?: () => void;
+    /** Closes the pass opened by `beginValidationPass`. */
+    endValidationPass?: () => void;
 }
 export type AddWiring = (logger: InspectorLogger, node: ts.Node, checker: ts.TypeChecker, state: InspectorState, options: InspectorOptions) => void;
 export interface InspectorFilesAndMethods {

package/dist/utils/post-process.js

@@ -4,6 +4,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';
@@ -79,18 +80,16 @@ function extractAllServices(state) {
         return;
     }
     // 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();
     }
@@ -898,11 +897,11 @@ export function validateNoSecretAliasServices(logger, checker, state) {
     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/dist/utils/resolve-core-type.d.ts

@@ -0,0 +1,21 @@
+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 declare const resolveCoreType: (typesLookup: Map<string, ts.Type[]>, importMap: PathToNameAndType) => ts.Type | undefined;

package/dist/utils/resolve-core-type.js

@@ -0,0 +1,29 @@
+/**
+ * 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, importMap) => {
+    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;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.64",
+  "version": "0.12.66",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.94"
+    "@pikku/core": "^0.12.96"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.94",
+    "@pikku/core": "^0.12.96",
     "@types/node": "^24.13.3"
   },
   "engines": {

package/src/add/add-cli.ts

@@ -11,6 +11,7 @@ import {
   extractFunctionName,
   makeContextBasedId,
 } from '../utils/extract-function-name.js'
+import { resolveCoreType } from '../utils/resolve-core-type.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
 import { extractWireNames } from '../utils/post-process.js'
@@ -825,8 +826,11 @@ function extractEnumFromConfigType(
   _inspectorOptions: InspectorOptions
 ): string[] | null {
   // Look for Config type in typesLookup
-  const configTypes = inspectorState.typesLookup.get('Config')
-  if (!configTypes || configTypes.length === 0) {
+  const configType = resolveCoreType(
+    inspectorState.typesLookup,
+    inspectorState.configTypeImportMap
+  )
+  if (!configType) {
     // Only warn once per CLI file to avoid spamming logs
     if (!configTypeWarningShown.has('missing-config-type')) {
       configTypeWarningShown.add('missing-config-type')
@@ -838,16 +842,6 @@ function extractEnumFromConfigType(
     return null
   }
 
-  // Use the first Config type (there should only be one)
-  const configType = configTypes[0]
-  if (!configType) {
-    if (!configTypeWarningShown.has('undefined-config-type')) {
-      configTypeWarningShown.add('undefined-config-type')
-      logger.warn(`Config type is undefined in typesLookup.`)
-    }
-    return null
-  }
-
   // Extract enum from the property
   return extractEnumFromPropertyType(configType, propertyName, typeChecker)
 }

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

@@ -110,4 +110,54 @@ export const routes = { stream: { func: ref('console:streamWorkflowRun') } }
       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 })
+    }
+  })
 })

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

@@ -20,6 +20,26 @@ function findCastArg(
   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'
  */
@@ -80,11 +100,15 @@ export function addRPCInvocations(
     }
 
     // Check for rpc.invoke('...') calls
+    const invokeReceiver = ts.isPropertyAccessExpression(expression)
+      ? invocationReceiver(expression.expression)
+      : undefined
     if (
       ts.isPropertyAccessExpression(expression) &&
       expression.name.text === 'invoke' &&
-      ts.isIdentifier(expression.expression) &&
-      expression.expression.text === 'rpc'
+      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).

package/src/index.ts

@@ -63,3 +63,4 @@ export type {
   SerializedWorkflowGraph,
   SerializedWorkflowGraphs,
 } from './utils/workflow/graph/index.js'
+export { resolveCoreType } from './utils/resolve-core-type.js'

package/src/inspector.ts

@@ -493,6 +493,10 @@ export const inspect = async (
   )
 
   if (!options.setupOnly) {
+    // Everything below re-derives from the state this pass just built, so it
+    // supersedes whatever an earlier pass concluded about a source graph the
+    // run has since finished generating into.
+    logger.beginValidationPass?.()
     const startAggregate = performance.now()
     // Apply the inspected auth handler service set before aggregation so it
     // flows into requiredServices (the generated handler's own func is opaque).
@@ -542,6 +546,7 @@ export const inspect = async (
     validateScopeReferences(logger, state)
     validateSystemRoleScopes(logger, state)
     validatePersonaRoles(logger, state)
+    logger.endValidationPass?.()
   }
 
   state.program = program

package/src/types.ts

@@ -366,6 +366,24 @@ export interface InspectorLogger {
   /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */
   critical: (code: ErrorCode, message: string) => void
   hasCriticalErrors: () => boolean
+  /**
+   * Opens a validation pass, discarding whatever a previous one recorded.
+   *
+   * A single `pikku all` inspects several times, because generating the
+   * scaffold, the leaf indexes and the type files each changes the source graph
+   * the next inspection reads. The validators are pure functions of that graph
+   * and every full inspection re-runs all of them, so the newest pass is always
+   * the complete one and the ones before it are strictly superseded.
+   *
+   * Without this the diagnostics accumulated instead, and a run failed on a
+   * complaint about its own half-built input: a project whose roles reference
+   * scaffold-declared scopes was reported as failing even though the pass that
+   * ran once the scaffold existed was clean. Optional so a host supplying its
+   * own logger keeps working — one that omits it simply never discards.
+   */
+  beginValidationPass?: () => void
+  /** Closes the pass opened by `beginValidationPass`. */
+  endValidationPass?: () => void
 }
 
 export type AddWiring = (

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/)
+  })
+})