@pikku/inspector 0.11.1 → 0.12.0

package/dist/types.d.ts

@@ -2,13 +2,21 @@ import * as ts from 'typescript';
 import { ChannelsMeta } from '@pikku/core/channel';
 import { HTTPWiringsMeta } from '@pikku/core/http';
 import { ScheduledTasksMeta } from '@pikku/core/scheduler';
+import { TriggerMeta, TriggerSourceMeta } from '@pikku/core/trigger';
 import { QueueWorkersMeta } from '@pikku/core/queue';
 import { WorkflowsMeta } from '@pikku/core/workflow';
 import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
+import { AIAgentMeta } from '@pikku/core/ai-agent';
 import { CLIMeta } from '@pikku/core/cli';
+import { NodesMeta } from '@pikku/core/node';
+import { SecretDefinitions } from '@pikku/core/secret';
+import { VariableDefinitions } from '@pikku/core/variable';
 import { TypesMap } from './types-map.js';
-import { FunctionsMeta, FunctionServicesMeta } from '@pikku/core';
+import { FunctionsMeta, FunctionServicesMeta, FunctionWiresMeta, JSONValue } from '@pikku/core';
+import type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 import { ErrorCode } from './error-codes.js';
+import type { VersionManifest, VersionValidateError } from './utils/contract-hashes.js';
+import type { SerializedWorkflowGraphs } from './utils/workflow/graph/workflow-graph.types.js';
 export type PathToNameAndType = Map<string, {
     variable: string;
     type: string | null;
@@ -24,7 +32,8 @@ export interface MiddlewareGroupMeta {
     sourceFile: string;
     position: number;
     services: FunctionServicesMeta;
-    middlewareCount: number;
+    count: number;
+    instanceIds: string[];
     isFactory: boolean;
 }
 export interface PermissionGroupMeta {
@@ -32,7 +41,8 @@ export interface PermissionGroupMeta {
     sourceFile: string;
     position: number;
     services: FunctionServicesMeta;
-    permissionCount: number;
+    count: number;
+    instanceIds: string[];
     isFactory: boolean;
 }
 export interface InspectorHTTPState {
@@ -42,6 +52,19 @@ export interface InspectorHTTPState {
     routeMiddleware: Map<string, MiddlewareGroupMeta>;
     routePermissions: Map<string, PermissionGroupMeta>;
 }
+/**
+ * Schema vendor types for Standard Schema compliant validators
+ */
+export type SchemaVendor = 'zod' | 'valibot' | 'arktype' | 'effect' | 'unknown';
+/**
+ * Schema reference for deferred conversion to JSON Schema at build time.
+ * Supports Standard Schema compliant validators (Zod, Valibot, ArkType, Effect Schema).
+ */
+export interface SchemaRef {
+    variableName: string;
+    sourceFile: string;
+    vendor?: SchemaVendor;
+}
 export interface InspectorFunctionState {
     typesMap: TypesMap;
     meta: FunctionsMeta;
@@ -54,28 +77,57 @@ export interface InspectorChannelState {
     meta: ChannelsMeta;
     files: Set<string>;
 }
+export interface InspectorMiddlewareDefinition {
+    services: FunctionServicesMeta;
+    wires?: FunctionWiresMeta;
+    sourceFile: string;
+    position: number;
+    exportedName: string | null;
+    factory?: boolean;
+    name?: string;
+    description?: string;
+    package?: string;
+}
+export interface InspectorMiddlewareInstance {
+    definitionId: string;
+    sourceFile: string;
+    position: number;
+    isFactoryCall: boolean;
+}
 export interface InspectorMiddlewareState {
-    meta: Record<string, {
-        services: FunctionServicesMeta;
-        sourceFile: string;
-        position: number;
-        exportedName: string | null;
-        factory?: boolean;
-        name?: string;
-        description?: string;
-    }>;
+    definitions: Record<string, InspectorMiddlewareDefinition>;
+    instances: Record<string, InspectorMiddlewareInstance>;
     tagMiddleware: Map<string, MiddlewareGroupMeta>;
 }
+export interface InspectorChannelMiddlewareState {
+    definitions: Record<string, InspectorMiddlewareDefinition>;
+    instances: Record<string, InspectorMiddlewareInstance>;
+    tagMiddleware: Map<string, MiddlewareGroupMeta>;
+}
+export interface InspectorAIMiddlewareState {
+    definitions: Record<string, InspectorMiddlewareDefinition>;
+}
+export interface InspectorPermissionDefinition {
+    services: FunctionServicesMeta;
+    wires?: FunctionWiresMeta;
+    sourceFile: string;
+    position: number;
+    exportedName: string | null;
+    factory?: boolean;
+    name?: string;
+    description?: string;
+    package?: string;
+    requiresData?: boolean;
+}
+export interface InspectorPermissionInstance {
+    definitionId: string;
+    sourceFile: string;
+    position: number;
+    isFactoryCall: boolean;
+}
 export interface InspectorPermissionState {
-    meta: Record<string, {
-        services: FunctionServicesMeta;
-        sourceFile: string;
-        position: number;
-        exportedName: string | null;
-        factory?: boolean;
-        name?: string;
-        description?: string;
-    }>;
+    definitions: Record<string, InspectorPermissionDefinition>;
+    instances: Record<string, InspectorPermissionInstance>;
     tagPermissions: Map<string, PermissionGroupMeta>;
 }
 export type InspectorFilters = {
@@ -86,14 +138,53 @@ export type InspectorFilters = {
     httpRoutes?: string[];
     httpMethods?: string[];
 };
+export type ExternalPackageConfig = {
+    package: string;
+    rpcEndpoint?: string;
+    secretOverrides?: Record<string, string>;
+    forceInclude?: boolean;
+};
+export type ModelConfigEntry = string | {
+    model: string;
+    temperature?: number;
+    maxSteps?: number;
+};
+export type InspectorModelConfig = {
+    models?: Record<string, ModelConfigEntry>;
+    agentDefaults?: {
+        temperature?: number;
+        maxSteps?: number;
+    };
+    agentOverrides?: Record<string, {
+        model?: string;
+        temperature?: number;
+        maxSteps?: number;
+    }>;
+};
 export type InspectorOptions = Partial<{
     setupOnly: boolean;
+    rootDir: string;
+    isExternalPackage: boolean;
     types: Partial<{
         configFileType: string;
         userSessionType: string;
         singletonServicesFactoryType: string;
         wireServicesFactoryType: string;
     }>;
+    externalPackages: Record<string, ExternalPackageConfig>;
+    schemaConfig: {
+        tsconfig: string;
+        schemasFromTypes?: string[];
+        schema?: {
+            additionalProperties?: boolean;
+        };
+    };
+    openAPI: {
+        additionalInfo: OpenAPISpecInfo;
+    };
+    tags: string[];
+    manifest: VersionManifest;
+    modelConfig: InspectorModelConfig;
 }>;
 export interface InspectorLogger {
     info: (message: string) => void;
@@ -148,6 +239,12 @@ export interface InspectorFilesAndMethods {
         typePath: string;
     };
 }
+export interface InspectorDiagnostic {
+    code: string;
+    message: string;
+    sourceFile: string;
+    position: number;
+}
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
@@ -161,9 +258,16 @@ export interface InspectorState {
     filesAndMethods: InspectorFilesAndMethods;
     filesAndMethodsErrors: Map<string, PathToNameAndType>;
     typesLookup: Map<string, ts.Type[]>;
+    schemaLookup: Map<string, SchemaRef>;
+    schemas: Record<string, JSONValue>;
     http: InspectorHTTPState;
     functions: InspectorFunctionState;
     channels: InspectorChannelState;
+    triggers: {
+        meta: TriggerMeta;
+        sourceMeta: TriggerSourceMeta;
+        files: Set<string>;
+    };
     scheduledTasks: {
         meta: ScheduledTasksMeta;
         files: Set<string>;
@@ -178,6 +282,12 @@ export interface InspectorState {
             path: string;
             exportedName: string;
         }>;
+        graphMeta: SerializedWorkflowGraphs;
+        graphFiles: Map<string, {
+            path: string;
+            exportedName: string;
+        }>;
+        invokedWorkflows: Set<string>;
     };
     rpc: {
         internalMeta: Record<string, string>;
@@ -191,6 +301,7 @@ export interface InspectorState {
             exportedName: string;
         }>;
         invokedFunctions: Set<string>;
+        usedExternalPackages: Set<string>;
     };
     mcpEndpoints: {
         resourcesMeta: MCPResourceMeta;
@@ -198,11 +309,37 @@ export interface InspectorState {
         promptsMeta: MCPPromptMeta;
         files: Set<string>;
     };
+    agents: {
+        agentsMeta: AIAgentMeta;
+        files: Map<string, {
+            path: string;
+            exportedName: string;
+        }>;
+    };
     cli: {
         meta: CLIMeta;
         files: Set<string>;
     };
+    nodes: {
+        meta: NodesMeta;
+        files: Set<string>;
+    };
+    secrets: {
+        definitions: SecretDefinitions;
+        files: Set<string>;
+    };
+    variables: {
+        definitions: VariableDefinitions;
+        files: Set<string>;
+    };
+    manifest: {
+        initial: VersionManifest | null;
+        current: VersionManifest | null;
+        errors: VersionValidateError[];
+    };
     middleware: InspectorMiddlewareState;
+    channelMiddleware: InspectorChannelMiddlewareState;
+    aiMiddleware: InspectorAIMiddlewareState;
     permissions: InspectorPermissionState;
     serviceAggregation: {
         requiredServices: Set<string>;
@@ -212,14 +349,27 @@ export interface InspectorState {
         allSingletonServices: string[];
         allWireServices: string[];
     };
-    serviceMetadata: Array<{
-        name: string;
-        summary: string;
-        description: string;
-        package: string;
-        path: string;
-        version: string;
-        interface: string;
-        expandedProperties: Record<string, string>;
+    resolvedIOTypes: Record<string, {
+        inputType: string;
+        outputType: string;
     }>;
+    middlewareGroupsMeta: {
+        definitions: Record<string, InspectorMiddlewareDefinition>;
+        instances: Record<string, InspectorMiddlewareInstance>;
+        httpGroups: Record<string, MiddlewareGroupMeta>;
+        tagGroups: Record<string, MiddlewareGroupMeta>;
+        channelMiddleware: {
+            definitions: Record<string, InspectorMiddlewareDefinition>;
+            instances: Record<string, InspectorMiddlewareInstance>;
+            tagGroups: Record<string, MiddlewareGroupMeta>;
+        };
+    };
+    permissionsGroupsMeta: {
+        definitions: Record<string, InspectorPermissionDefinition>;
+        httpGroups: Record<string, PermissionGroupMeta>;
+        tagGroups: Record<string, PermissionGroupMeta>;
+    };
+    requiredSchemas: Set<string>;
+    openAPISpec: Record<string, any> | null;
+    diagnostics: InspectorDiagnostic[];
 }

package/dist/utils/compute-required-schemas.d.ts

@@ -0,0 +1,4 @@
+import type { FunctionsMeta } from '@pikku/core';
+import type { TypesMap } from '../types-map.js';
+import type { SchemaRef } from '../types.js';
+export declare function computeRequiredSchemas(functionsMeta: FunctionsMeta, typesMap: TypesMap, additionalTypes?: string[], schemaLookup?: Map<string, SchemaRef>): Set<string>;

package/dist/utils/compute-required-schemas.js

@@ -0,0 +1,41 @@
+const PRIMITIVE_TYPES = new Set([
+    'boolean',
+    'string',
+    'number',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
+]);
+export function computeRequiredSchemas(functionsMeta, typesMap, additionalTypes, schemaLookup) {
+    return new Set([
+        ...Object.values(functionsMeta)
+            .map(({ inputs, outputs }) => {
+            const types = [];
+            if (inputs?.[0]) {
+                try {
+                    types.push(typesMap.getUniqueName(inputs[0]));
+                }
+                catch {
+                    types.push(inputs[0]);
+                }
+            }
+            if (outputs?.[0]) {
+                try {
+                    types.push(typesMap.getUniqueName(outputs[0]));
+                }
+                catch {
+                    types.push(outputs[0]);
+                }
+            }
+            return types;
+        })
+            .flat()
+            .filter((s) => !!s && !PRIMITIVE_TYPES.has(s)),
+        ...typesMap.customTypes.keys(),
+        ...(additionalTypes || []),
+        ...(schemaLookup ? Array.from(schemaLookup.keys()) : []),
+    ]);
+}

package/dist/utils/contract-hashes.d.ts

@@ -0,0 +1,35 @@
+import { FunctionsMeta, JSONValue } from '@pikku/core';
+import { TypesMap } from '../types-map.js';
+import { ErrorCode } from '../error-codes.js';
+export type ContractEntry = {
+    functionKey: string;
+    version: number;
+    contractHash: string;
+};
+export type VersionValidateError = {
+    code: ErrorCode;
+    message: string;
+};
+export type VersionManifestEntry = {
+    latest: number;
+    versions: Record<string, string>;
+};
+export type VersionManifest = {
+    manifestVersion: 1;
+    contracts: Record<string, VersionManifestEntry>;
+};
+export declare function createEmptyManifest(): VersionManifest;
+export declare function serializeManifest(manifest: VersionManifest): string;
+export declare function computeContractHash(data: {
+    functionKey: string;
+    inputSchema: unknown;
+    outputSchema: unknown;
+}): string;
+export declare function buildCurrentContracts(functionsMeta: FunctionsMeta, allSchemas: Record<string, JSONValue>, typesMap: TypesMap): Map<string, ContractEntry>;
+export declare function computeContractHashes(allSchemas: Record<string, JSONValue>, typesMap: TypesMap, functionsMeta: FunctionsMeta): Map<string, ContractEntry>;
+export declare function validateContracts(manifest: VersionManifest, currentContracts: Map<string, ContractEntry>): {
+    valid: boolean;
+    errors: VersionValidateError[];
+};
+export declare function updateManifest(existing: VersionManifest, currentContracts: Map<string, ContractEntry>): VersionManifest;
+export declare function extractContractsFromMeta(functionsMeta: FunctionsMeta): Map<string, ContractEntry>;

package/dist/utils/contract-hashes.js

@@ -0,0 +1,202 @@
+import { parseVersionedId } from '@pikku/core';
+import { ErrorCode } from '../error-codes.js';
+import { canonicalJSON, hashString } from './hash.js';
+export function createEmptyManifest() {
+    return {
+        manifestVersion: 1,
+        contracts: {},
+    };
+}
+export function serializeManifest(manifest) {
+    const sortedContracts = {};
+    for (const key of Object.keys(manifest.contracts).sort()) {
+        const entry = manifest.contracts[key];
+        const sortedVersions = {};
+        const numericKeys = Object.keys(entry.versions)
+            .map(Number)
+            .sort((a, b) => a - b);
+        for (const vk of numericKeys) {
+            sortedVersions[String(vk)] = entry.versions[String(vk)];
+        }
+        sortedContracts[key] = {
+            latest: entry.latest,
+            versions: sortedVersions,
+        };
+    }
+    const sorted = {
+        manifestVersion: manifest.manifestVersion,
+        contracts: sortedContracts,
+    };
+    return JSON.stringify(sorted, null, 2) + '\n';
+}
+export function computeContractHash(data) {
+    return hashString(canonicalJSON(data), 16);
+}
+function resolveSchema(typeNames, allSchemas, typesMap) {
+    if (!typeNames) {
+        return null;
+    }
+    const filtered = typeNames.filter((n) => n !== 'void');
+    if (filtered.length === 0) {
+        return null;
+    }
+    const parts = [];
+    for (const name of filtered) {
+        let key;
+        try {
+            key = typesMap.getUniqueName(name);
+        }
+        catch {
+            key = name;
+        }
+        const schema = allSchemas[key];
+        if (schema) {
+            parts.push(schema);
+        }
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.length === 1 ? parts[0] : parts;
+}
+export function buildCurrentContracts(functionsMeta, allSchemas, typesMap) {
+    const result = new Map();
+    for (const [funcId, meta] of Object.entries(functionsMeta)) {
+        if (meta.remote === true) {
+            continue;
+        }
+        const parsed = parseVersionedId(funcId);
+        const functionKey = parsed.baseName;
+        const version = parsed.version ?? meta.version ?? 1;
+        const inputSchema = resolveSchema(meta.inputs, allSchemas, typesMap);
+        const outputSchema = resolveSchema(meta.outputs, allSchemas, typesMap);
+        const contractHash = computeContractHash({
+            functionKey,
+            inputSchema,
+            outputSchema,
+        });
+        result.set(funcId, { functionKey, version, contractHash });
+    }
+    return result;
+}
+export function computeContractHashes(allSchemas, typesMap, functionsMeta) {
+    const contracts = buildCurrentContracts(functionsMeta, allSchemas, typesMap);
+    for (const [funcId, entry] of contracts) {
+        const meta = functionsMeta[funcId];
+        if (meta) {
+            meta.contractHash = entry.contractHash;
+        }
+    }
+    return contracts;
+}
+function groupByFunctionKey(contracts) {
+    const grouped = new Map();
+    for (const entry of contracts.values()) {
+        const existing = grouped.get(entry.functionKey) ?? [];
+        existing.push(entry);
+        grouped.set(entry.functionKey, existing);
+    }
+    return grouped;
+}
+export function validateContracts(manifest, currentContracts) {
+    const errors = [];
+    const grouped = groupByFunctionKey(currentContracts);
+    const reportedKeys = new Set();
+    for (const [functionKey, entries] of grouped) {
+        const manifestEntry = manifest.contracts[functionKey];
+        if (!manifestEntry) {
+            continue;
+        }
+        for (const { version, contractHash } of entries) {
+            const existingHash = manifestEntry.versions[String(version)];
+            if (existingHash !== undefined) {
+                if (existingHash !== contractHash) {
+                    reportedKeys.add(`${functionKey}@${version}`);
+                    errors.push({
+                        code: ErrorCode.FUNCTION_VERSION_MODIFIED,
+                        message: `Contract for ${functionKey}@v${version} has changed (recorded: ${existingHash}, current: ${contractHash}). Existing versions are immutable.`,
+                    });
+                }
+            }
+            else {
+                if (version <= manifestEntry.latest) {
+                    errors.push({
+                        code: ErrorCode.VERSION_REGRESSION_OR_CONFLICT,
+                        message: `Version ${version} for ${functionKey} is <= latest (${manifestEntry.latest}) but not recorded. Possible merge conflict.`,
+                    });
+                }
+                else if (version > manifestEntry.latest + 1) {
+                    errors.push({
+                        code: ErrorCode.VERSION_GAP_NOT_ALLOWED,
+                        message: `Version ${version} for ${functionKey} skips versions. Latest is ${manifestEntry.latest}, next must be ${manifestEntry.latest + 1}.`,
+                    });
+                }
+            }
+        }
+    }
+    for (const [functionKey, manifestEntry] of Object.entries(manifest.contracts)) {
+        const latestHash = manifestEntry.versions[String(manifestEntry.latest)];
+        const currentEntries = grouped.get(functionKey);
+        if (!currentEntries) {
+            continue;
+        }
+        const currentLatest = currentEntries.find((e) => e.version === manifestEntry.latest);
+        if (currentLatest &&
+            currentLatest.contractHash !== latestHash &&
+            !reportedKeys.has(`${functionKey}@${manifestEntry.latest}`)) {
+            errors.push({
+                code: ErrorCode.CONTRACT_CHANGED_REQUIRES_BUMP,
+                message: `Contract for ${functionKey} changed. Set \`version: ${manifestEntry.latest + 1}\` on the function or run 'pikku versions update'.`,
+            });
+        }
+    }
+    for (const [functionKey, manifestEntry] of Object.entries(manifest.contracts)) {
+        const numericKeys = Object.keys(manifestEntry.versions).map(Number);
+        if (numericKeys.length === 0) {
+            continue;
+        }
+        const maxVersion = Math.max(...numericKeys);
+        if (manifestEntry.latest !== maxVersion) {
+            errors.push({
+                code: ErrorCode.MANIFEST_INTEGRITY_ERROR,
+                message: `Manifest integrity error for ${functionKey}: latest field (${manifestEntry.latest}) inconsistent with version keys (max: ${maxVersion}).`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function updateManifest(existing, currentContracts) {
+    const manifest = {
+        manifestVersion: existing.manifestVersion,
+        contracts: JSON.parse(JSON.stringify(existing.contracts)),
+    };
+    const grouped = groupByFunctionKey(currentContracts);
+    for (const [functionKey, entries] of grouped) {
+        if (!manifest.contracts[functionKey]) {
+            manifest.contracts[functionKey] = { latest: 0, versions: {} };
+        }
+        const entry = manifest.contracts[functionKey];
+        for (const { version, contractHash } of entries) {
+            entry.versions[String(version)] = contractHash;
+            entry.latest = Math.max(entry.latest, version);
+        }
+    }
+    return manifest;
+}
+export function extractContractsFromMeta(functionsMeta) {
+    const result = new Map();
+    for (const [funcId, meta] of Object.entries(functionsMeta)) {
+        if (meta.remote === true || !meta.contractHash) {
+            continue;
+        }
+        const parsed = parseVersionedId(funcId);
+        const functionKey = parsed.baseName;
+        const version = parsed.version ?? meta.version ?? 1;
+        result.set(funcId, {
+            functionKey,
+            version,
+            contractHash: meta.contractHash,
+        });
+    }
+    return result;
+}

package/dist/utils/custom-types-generator.d.ts

@@ -0,0 +1,9 @@
+import { TypesMap } from '../types-map.js';
+/**
+ * NOTE: Code generation normally belongs in @pikku/cli, not the inspector.
+ * This is here because the schema generator needs the custom types content
+ * as a virtual TypeScript source file (in-memory, no disk write) so that
+ * ts-json-schema-generator can discover inline/custom types from typesMap.
+ */
+export declare function sanitizeTypeName(name: string): string;
+export declare function generateCustomTypes(typesMap: TypesMap, requiredTypes: Set<string>): string;

package/dist/utils/custom-types-generator.js

@@ -0,0 +1,71 @@
+/**
+ * NOTE: Code generation normally belongs in @pikku/cli, not the inspector.
+ * This is here because the schema generator needs the custom types content
+ * as a virtual TypeScript source file (in-memory, no disk write) so that
+ * ts-json-schema-generator can discover inline/custom types from typesMap.
+ */
+export function sanitizeTypeName(name) {
+    return name.replace(/[^a-zA-Z0-9_$]/g, '_');
+}
+export function generateCustomTypes(typesMap, requiredTypes) {
+    const typeDeclarations = Array.from(typesMap.customTypes.entries())
+        .filter(([_name, { type }]) => {
+        const hasUndefinedGeneric = /\b(Name|In|Out|Key)\b/.test(type) && /\[.*\]/.test(type);
+        return !hasUndefinedGeneric;
+    })
+        .map(([originalName, { type, references }]) => {
+        const name = sanitizeTypeName(originalName);
+        references.forEach((refName) => {
+            if (refName !== '__object' && !refName.startsWith('__object_')) {
+                requiredTypes.add(refName);
+            }
+        });
+        const typeString = type;
+        const typeNameRegex = /\b[A-Z][a-zA-Z0-9]*\b/g;
+        const potentialTypes = typeString.match(typeNameRegex) || [];
+        potentialTypes.forEach((typeName) => {
+            if (typeString.includes(`"${typeName}"`) ||
+                [
+                    'Pick',
+                    'Omit',
+                    'Partial',
+                    'Required',
+                    'Record',
+                    'Readonly',
+                ].includes(typeName)) {
+                return;
+            }
+            try {
+                const typeMeta = typesMap.getTypeMeta(typeName);
+                if (typeMeta.path) {
+                    requiredTypes.add(typeMeta.originalName);
+                }
+            }
+            catch {
+                // Type not found in map (ambient/builtin type)
+            }
+        });
+        if (name === type)
+            return null;
+        return `export type ${name} = ${type}`;
+    });
+    const importsByPath = new Map();
+    for (const typeName of requiredTypes) {
+        try {
+            const typeMeta = typesMap.getTypeMeta(typeName);
+            if (typeMeta.path) {
+                if (!importsByPath.has(typeMeta.path)) {
+                    importsByPath.set(typeMeta.path, new Set());
+                }
+                importsByPath.get(typeMeta.path).add(typeMeta.originalName);
+            }
+        }
+        catch {
+            // Type not found in map
+        }
+    }
+    const importLines = Array.from(importsByPath.entries())
+        .map(([path, types]) => `import type { ${Array.from(types).join(', ')} } from '${path}'`)
+        .join('\n');
+    return `${importLines}\n\n${typeDeclarations.filter(Boolean).join('\n')}`;
+}