@pikku/inspector 0.12.103 → 0.12.107

package/dist/inspector.js

@@ -1,243 +1,21 @@
 import * as ts from 'typescript';
-import { applyDeclaredScopes } from './add/add-scope.js';
 import { performance } from 'perf_hooks';
 import { dirname, relative, resolve } from 'path';
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
-import { TypesMap } from './types-map.js';
-import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { toProgramPath } from './utils/program-path.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
-import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
-import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
-import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
-import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
-import { pikkuState } from '@pikku/core/state';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { validateWebhookSourceTriggers } from './add/add-trigger.js';
-import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
-import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
 import { generateAllSchemas } from './utils/schema-generator.js';
 import { extractSecretUsage } from './utils/extract-secret-usage.js';
 import { accumulateSurfaceUsage, surfaceUsageArea, } from './utils/extract-surface-usage.js';
-import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
-import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
-/**
- * Creates an initial/empty inspector state with all required properties initialized
- * @param rootDir - The root directory for the project
- * @returns A fresh InspectorState with empty collections
- */
-export function getInitialInspectorState(rootDir) {
-    return {
-        rootDir,
-        singletonServicesTypeImportMap: new Map(),
-        wireServicesTypeImportMap: new Map(),
-        userSessionTypeImportMap: new Map(),
-        configTypeImportMap: new Map(),
-        singletonServicesFactories: new Map(),
-        wireServicesFactories: new Map(),
-        wireServicesMeta: new Map(),
-        addonRequiredParentServices: [],
-        addonCreatedServices: [],
-        addonServicesFactorySeen: false,
-        addonServerlessIncompatible: new Map(),
-        configFactories: new Map(),
-        serverLifecycleFactories: new Map(),
-        filesAndMethods: {},
-        filesAndMethodsErrors: new Map(),
-        typesLookup: new Map(),
-        schemaLookup: new Map(),
-        schemas: {},
-        functions: {
-            typesMap: new TypesMap(),
-            meta: {},
-            files: new Map(),
-            approvalDescriptions: {},
-            dynamicImportIds: new Set(),
-        },
-        http: {
-            metaInputTypes: new Map(),
-            meta: {
-                get: {},
-                post: {},
-                put: {},
-                delete: {},
-                head: {},
-                patch: {},
-                options: {},
-            },
-            files: new Set(),
-            routeMiddleware: new Map(),
-        },
-        channels: {
-            files: new Set(),
-            meta: {},
-        },
-        gateways: {
-            meta: {},
-            files: new Set(),
-        },
-        triggers: {
-            meta: {},
-            sourceMeta: {},
-            webhookSourceMeta: {},
-            files: new Set(),
-        },
-        scheduledTasks: {
-            meta: {},
-            files: new Set(),
-        },
-        queueWorkers: {
-            meta: {},
-            files: new Set(),
-        },
-        workflows: {
-            meta: {},
-            files: new Map(),
-            graphMeta: {},
-            graphFiles: new Map(),
-            featureFiles: new Map(),
-            invokedWorkflows: new Set(),
-        },
-        rpc: {
-            internalMeta: {},
-            internalFiles: new Map(),
-            exposedMeta: {},
-            exposedFiles: new Map(),
-            remoteMeta: {},
-            remoteFiles: new Map(),
-            invokedFunctions: new Set(),
-            invokedFunctionsByFile: new Map(),
-            usedAddons: new Set(),
-            wireAddonDeclarations: new Map(),
-            wireAddonFiles: new Set(),
-        },
-        mcpEndpoints: {
-            resourcesMeta: {},
-            toolsMeta: {},
-            promptsMeta: {},
-            files: new Set(),
-            surfaces: {},
-        },
-        agents: {
-            agentsMeta: {},
-            files: new Map(),
-            invokedAgentsByFile: new Map(),
-        },
-        scorers: {
-            scorersMeta: {},
-            files: new Map(),
-        },
-        cli: {
-            meta: {
-                programs: {},
-                renderers: {},
-            },
-            files: new Set(),
-        },
-        nodes: {
-            meta: {},
-            files: new Set(),
-        },
-        auth: {
-            providers: [],
-            plugins: [],
-            files: new Set(),
-            definition: null,
-        },
-        secrets: {
-            definitions: [],
-            files: new Set(),
-            usage: new Map(),
-        },
-        surfaceUsage: {},
-        credentials: {
-            definitions: [],
-            files: new Set(),
-        },
-        scopes: {
-            definitions: [],
-            files: new Set(),
-        },
-        systemRoles: {
-            definitions: [],
-            files: new Set(),
-        },
-        featureFlags: {
-            definitions: [],
-            files: new Set(),
-        },
-        personas: {
-            definitions: [],
-            files: new Set(),
-        },
-        variables: {
-            definitions: [],
-            files: new Set(),
-        },
-        manifest: {
-            initial: null,
-            current: null,
-            errors: [],
-        },
-        middleware: {
-            definitions: {},
-            instances: {},
-            tagMiddleware: new Map(),
-            globalFiles: new Set(),
-        },
-        channelMiddleware: {
-            definitions: {},
-            instances: {},
-            tagMiddleware: new Map(),
-        },
-        agentMiddleware: {
-            definitions: {},
-        },
-        permissions: {
-            definitions: {},
-            instances: {},
-        },
-        serviceAggregation: {
-            requiredServices: new Set(),
-            usedFunctions: new Set(),
-            usedMiddleware: new Set(),
-            usedPermissions: new Set(),
-            allSingletonServices: [],
-            allWireServices: [],
-        },
-        resolvedIOTypes: {},
-        middlewareGroupsMeta: {
-            definitions: {},
-            instances: {},
-            httpGroups: {},
-            tagGroups: {},
-            channelMiddleware: {
-                definitions: {},
-                instances: {},
-                tagGroups: {},
-            },
-        },
-        permissionsGroupsMeta: {
-            definitions: {},
-        },
-        requiredSchemas: new Set(),
-        openAPISpec: null,
-        diagnostics: [],
-        addonFunctions: {},
-        exportedContracts: {
-            http: {},
-            cli: {},
-            channel: {},
-            addonHttp: {},
-            addonCli: {},
-            addonChannel: {},
-        },
-        program: null,
-    };
-}
+import { loadAddonFunctionsMeta } from './utils/load-addon-functions-meta.js';
+import { resolveServiceTypes } from './utils/resolve-service-types.js';
+import { finalizeInspectorState } from './finalize.js';
+import { getInitialInspectorState } from './initial-state.js';
+export { getInitialInspectorState };
 /**
  * The path mappings the inspector's program has to share with the project.
  *
@@ -271,7 +49,12 @@ const readProjectPathMappings = (logger, tsconfig) => {
         ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
     };
 };
-export const inspect = async (logger, routeFiles, options = {}) => {
+/**
+ * The engine-specific half of an inspection: builds the program, walks it with
+ * the checker and generates the schemas. What it returns is the pre-finalize
+ * state that `finalizeInspectorState` completes.
+ */
+export const analyzeProgram = async (logger, routeFiles, options = {}) => {
     const normalizedRouteFiles = routeFiles.map((file) => resolve(file));
     const compilerOptions = {
         ...readProjectPathMappings(logger, options.tsconfig),
@@ -363,80 +146,11 @@ export const inspect = async (logger, routeFiles, options = {}) => {
             const startSchemas = performance.now();
             state.schemas = await generateAllSchemas(logger, options.schemaConfig, state);
             logger.debug(`generateAllSchemas took ${(performance.now() - startSchemas).toFixed(0)}ms`);
-            computeContractHashes(state.schemas, state.functions.typesMap, state.functions.meta);
-            computeRequiredSchemas(state, options);
-        }
-        // Re-load addon schemas (generateAllSchemas replaces state.schemas)
-        await loadAddonSchemas(logger, state);
-        // After the addon merge, not before: an addon supplies its own schemas here,
-        // and checking earlier would report every one of them as unresolved.
-        if (options.schemaConfig) {
-            validateSchemaReferences(logger, state);
         }
-        state.manifest.initial = options.manifest ?? null;
-        const contracts = extractContractsFromMeta(state.functions.meta);
-        const baseManifest = state.manifest.initial ?? createEmptyManifest();
-        state.manifest.current = updateManifest(baseManifest, contracts);
-        state.manifest.errors = validateContracts(baseManifest, contracts).errors;
-        finalizeWorkflows(state);
-        finalizeWorkflowHelperTypes(state);
-        finalizeWorkflowWires(state);
-    }
-    // Populate filesAndMethods
-    const startFilesAndMethods = performance.now();
-    const { result, errors } = getFilesAndMethods(state, options.types);
-    state.filesAndMethods = result;
-    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).
-        stampAuthHandlerServices(state);
-        aggregateRequiredServices(state);
-        logger.debug(`Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`);
-        computeResolvedIOTypes(state);
-        computeMiddlewareGroupsMeta(state);
-        computePermissionsGroupsMeta(state);
-        validateNoSecretAliasServices(logger, checker, state);
-        registerDerivedOAuth2AppSecrets(state);
-        validateSecretUsage(logger, state);
-        computeDiagnostics(state);
-        validateSchemaWiringSeparation(logger, state);
-        validateWorkflowGraphAddons(logger, state);
-        validateScenarioServices(logger, state);
-        validateScenarioSteps(logger, state);
-        validateScenarioFeatures(logger, state);
-        // Needs every route, every function and every wireAddon declaration
-        // together, so it can only run once the whole program is inspected.
-        annotateHttpRouteAuth(state);
-        // Last of the validators: they read function meta and every wireAddon
-        // declaration together, so they need the whole program inspected.
-        validateExposedFunctionsGated(logger, state);
-        validateTagsResolveToMiddleware(logger, state);
-        if (options.openAPI) {
-            state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));
-        }
-        validateAgentModels(logger, state, options.modelAliases);
-        validateAgentToolReferences(logger, state, options);
-        validateAgentScorerReferences(logger, state);
-        validateSecretOverrides(logger, state);
-        validateVariableOverrides(logger, state);
-        validateCredentialOverrides(logger, state);
-        validateAddonUses(logger, state);
-        validateAddonContentGrants(logger, state);
-        validateRemoteAddonDependencies(logger, state);
-        validateRemoteAddonAuth(logger, state);
-        applyDeclaredScopes(state);
-        validateScopeReferences(logger, state);
-        validateSystemRoleScopes(logger, state);
-        validatePersonaRoles(logger, state);
-        logger.endValidationPass?.();
     }
+    // On a setup-only pass too: the CLI reads the singleton service names off
+    // a setup-only state to decide whether workflows have a workflowService.
+    state.serviceTypes = resolveServiceTypes(state, checker);
     const cpu = process.cpuUsage(cpuStart);
     state.stats = {
         files: program.getSourceFiles().length,
@@ -452,3 +166,17 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     state.program = program;
     return state;
 };
+export const inspect = async (logger, routeFiles, options = {}) => {
+    const cpuStart = process.cpuUsage();
+    const start = performance.now();
+    const state = await analyzeProgram(logger, routeFiles, options);
+    await finalizeInspectorState(logger, state, options);
+    const cpu = process.cpuUsage(cpuStart);
+    state.stats = {
+        ...state.stats,
+        cpuMs: Math.round((cpu.user + cpu.system) / 1000),
+        wallMs: Math.round(performance.now() - start),
+        heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
+    };
+    return state;
+};

package/dist/lite.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The inspector's exports that never load the TypeScript compiler.
+ *
+ * `@pikku/inspector` itself pulls in `typescript` and `ts-json-schema-generator`
+ * at module load, which costs a CLI command that only wants an error code or a
+ * serializer most of its startup time, and costs the native engine the
+ * compiler's memory for nothing. Everything a consumer of an `InspectorState`
+ * needs is here and safe to import eagerly; `lite.test.ts` fails if anything
+ * reachable from this file imports `typescript`.
+ */
+export { getInitialInspectorState } from './initial-state.js';
+export { ErrorCode } from './error-codes.js';
+export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
+export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
+export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
+export { filterInspectorState } from './utils/filter-inspector-state.js';
+export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
+export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
+export { serializeMCPJson } from './utils/serialize-mcp-json.js';
+export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
+export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
+export { resolveCoreType } from './utils/resolve-core-type.js';
+export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';

package/dist/lite.js

@@ -0,0 +1,25 @@
+/**
+ * The inspector's exports that never load the TypeScript compiler.
+ *
+ * `@pikku/inspector` itself pulls in `typescript` and `ts-json-schema-generator`
+ * at module load, which costs a CLI command that only wants an error code or a
+ * serializer most of its startup time, and costs the native engine the
+ * compiler's memory for nothing. Everything a consumer of an `InspectorState`
+ * needs is here and safe to import eagerly; `lite.test.ts` fails if anything
+ * reachable from this file imports `typescript`.
+ */
+export { getInitialInspectorState } from './initial-state.js';
+export { ErrorCode } from './error-codes.js';
+export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
+export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
+export { filterInspectorState } from './utils/filter-inspector-state.js';
+export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
+export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
+export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
+export { serializeMCPJson } from './utils/serialize-mcp-json.js';
+export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
+export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
+export { resolveCoreType } from './utils/resolve-core-type.js';
+export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';

package/dist/source-file-cache.d.ts

@@ -1,4 +1,15 @@
 import * as ts from 'typescript';
+/**
+ * Parse through the shared cache. With `populate: false` the cache is only
+ * read: a short-lived program (the schema generator's) reuses what the
+ * inspector parsed without pinning its own files past its lifetime.
+ */
+export declare const getCachedSourceFile: (fileName: string, text: string, languageVersionOrOptions: ts.ScriptTarget | ts.CreateSourceFileOptions, { populate }?: {
+    populate?: boolean;
+}) => {
+    file: ts.SourceFile;
+    reused: boolean;
+};
 export interface SourceFileCacheHost extends ts.CompilerHost {
     /** Files served from the cache by the program just built. */
     readonly reused: () => number;

package/dist/source-file-cache.js

@@ -17,6 +17,35 @@ import { createHash } from 'crypto';
  * worth having if it outlives the call.
  */
 const cache = new Map();
+/**
+ * A SourceFile is only shareable between programs that would have parsed it
+ * the same way: the language version and the module format the program
+ * implies for it (ESM vs CJS) are baked into the AST. The inspector and the
+ * schema generator use different compiler options, so both go into the key.
+ */
+const cacheKey = (fileName, languageVersionOrOptions) => {
+    if (typeof languageVersionOrOptions !== 'object') {
+        return `${fileName}\0${languageVersionOrOptions}`;
+    }
+    const { languageVersion, impliedNodeFormat, jsDocParsingMode } = languageVersionOrOptions;
+    return `${fileName}\0${languageVersion}\0${impliedNodeFormat ?? ''}\0${jsDocParsingMode ?? ''}`;
+};
+/**
+ * Parse through the shared cache. With `populate: false` the cache is only
+ * read: a short-lived program (the schema generator's) reuses what the
+ * inspector parsed without pinning its own files past its lifetime.
+ */
+export const getCachedSourceFile = (fileName, text, languageVersionOrOptions, { populate = true } = {}) => {
+    const key = cacheKey(fileName, languageVersionOrOptions);
+    const hash = createHash('sha1').update(text).digest('hex');
+    const hit = cache.get(key);
+    if (hit && hit.hash === hash)
+        return { file: hit.file, reused: true };
+    const file = ts.createSourceFile(fileName, text, languageVersionOrOptions, true);
+    if (populate)
+        cache.set(key, { hash, file });
+    return { file, reused: false };
+};
 export const createSourceFileCacheHost = (options) => {
     const host = ts.createCompilerHost(options, true);
     let reused = 0;
@@ -31,23 +60,18 @@ export const createSourceFileCacheHost = (options) => {
         }
         if (text === undefined)
             return undefined;
-        const hash = createHash('sha1').update(text).digest('hex');
-        const hit = cache.get(fileName);
-        if (hit && hit.hash === hash) {
+        const { file, reused: hit } = getCachedSourceFile(fileName, text, languageVersionOrOptions);
+        if (hit)
             reused++;
-            return hit.file;
-        }
-        const file = ts.createSourceFile(fileName, text, languageVersionOrOptions, true);
-        cache.set(fileName, { hash, file });
         return file;
     };
     return Object.assign(host, {
         reused: () => reused,
         prune: (program) => {
             const live = new Set(program.getSourceFiles().map((sf) => sf.fileName));
-            for (const fileName of cache.keys()) {
-                if (!live.has(fileName))
-                    cache.delete(fileName);
+            for (const [key, entry] of cache) {
+                if (!live.has(entry.file.fileName))
+                    cache.delete(key);
             }
         },
     });

package/dist/types-map.js

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
+import { canonicalTypeString } from './utils/canonical-type-string.js';
 export class TypesMap {
     map = new Map();
     customTypes = new Map();
     addCustomType(name, type, references) {
-        this.customTypes.set(name, { type, references });
+        this.customTypes.set(name, { type: canonicalTypeString(type), references });
     }
     addType(originalName, path) {
         this.map.set(originalName, { originalName, path });

package/dist/types.d.ts

@@ -19,7 +19,7 @@ import type { CredentialDefinitions } from '@pikku/core/credential';
 import type { ScopeDefinitions } from '@pikku/core/scope';
 import type { SystemRoleDefinitions } from '@pikku/core/role';
 import type { FeatureFlagDefinitions } from '@pikku/core/flag';
-import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { VirtualUserDefinitions } from '@pikku/core/virtual-user';
 import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
 import type { FunctionsMeta } from '@pikku/core/services';
@@ -206,9 +206,21 @@ export interface InspectorPermissionInstance {
     position: number;
     isFactoryCall: boolean;
 }
+/**
+ * One `addGlobalPermission(...)` call. It registers at module evaluation, so
+ * codegen must import its file — or call `exportName`, when the call sits in an
+ * exported zero-argument factory — or the global gate does not exist.
+ */
+export interface InspectorGlobalPermissionRegistration {
+    sourceFile: string;
+    position: number;
+    exportName: string | null;
+    definitionIds: string[];
+}
 export interface InspectorPermissionState {
     definitions: Record<string, InspectorPermissionDefinition>;
     instances: Record<string, InspectorPermissionInstance>;
+    global: InspectorGlobalPermissionRegistration[];
 }
 export type InspectorFilters = {
     names?: string[];
@@ -428,6 +440,12 @@ export interface AuthDefinition {
     /** Whether `session.cookieCache` is enabled — drives the stateless session
      * middleware split in the auth codegen. Absent/false ⇒ stateful middleware. */
     cookieCache?: boolean;
+    /** `advanced.cookiePrefix`, when written as a string literal. */
+    cookiePrefix?: string;
+    /** `session.cookieCache.strategy`, when written as a string literal. */
+    cookieCacheStrategy?: string;
+    /** `session.cookieCache.version`, when written as a string literal. */
+    cookieCacheVersion?: string;
     /**
      * Singleton services the generated auth handler must have available at
      * runtime — the services the `pikkuBetterAuth` factory reaches for (either
@@ -518,6 +536,14 @@ export type ScreensManifestMeta = {
      */
     scopes?: string[];
 };
+export interface InspectorServiceTypes {
+    /** Property names of the project's SingletonServices type, sorted. */
+    singletonServices: string[] | null;
+    /** Property names of the project's Services type, unfiltered. */
+    services: string[] | null;
+    /** Singleton services that are a `SecretService` under another name. */
+    secretAliases: string[];
+}
 export interface InspectorState {
     /** Set when this package calls `defineScreens`: the screens it ships. */
     screensManifest?: ScreensManifestMeta;
@@ -784,8 +810,8 @@ export interface InspectorState {
         definitions: FeatureFlagDefinitions;
         files: Set<string>;
     };
-    personas: {
-        definitions: PersonaDefinitions;
+    virtualUsers: {
+        definitions: VirtualUserDefinitions;
         files: Set<string>;
     };
     variables: {
@@ -801,6 +827,12 @@ export interface InspectorState {
     channelMiddleware: InspectorChannelMiddlewareState;
     agentMiddleware: InspectorAIMiddlewareState;
     permissions: InspectorPermissionState;
+    /**
+     * What the checker concluded about the project's core service types, read
+     * during analysis so that finalize never needs `typesLookup`. A field is null
+     * when the type did not resolve.
+     */
+    serviceTypes?: InspectorServiceTypes;
     serviceAggregation: {
         requiredServices: Set<string>;
         usedFunctions: Set<string>;

package/dist/utils/apply-declared-scopes.d.ts

@@ -0,0 +1,8 @@
+import type { InspectorState } from '../types.js';
+/**
+ * Folds `declareScopes` ids into `state.scopes.definitions`. An id the
+ * definitions already hold (an addon's tree, a `defineScope`) is left alone;
+ * a missing one is added as a bare node under its root, creating the root when
+ * nothing declared it.
+ */
+export declare const applyDeclaredScopes: (state: Pick<InspectorState, "scopes">) => void;

package/dist/utils/apply-declared-scopes.js

@@ -0,0 +1,21 @@
+/**
+ * Folds `declareScopes` ids into `state.scopes.definitions`. An id the
+ * definitions already hold (an addon's tree, a `defineScope`) is left alone;
+ * a missing one is added as a bare node under its root, creating the root when
+ * nothing declared it.
+ */
+export const applyDeclaredScopes = (state) => {
+    for (const [id, sourceFile] of state.scopes.declared ?? []) {
+        const [rootName, ...rest] = id.split(':');
+        let root = state.scopes.definitions.find((d) => d.name === rootName);
+        if (!root) {
+            root = { name: rootName, sourceFile };
+            state.scopes.definitions.push(root);
+        }
+        let level = root;
+        for (const segment of rest) {
+            level.scopes ??= {};
+            level = level.scopes[segment] ??= {};
+        }
+    }
+};

package/dist/utils/canonical-type-string.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A printed type with the members of every union in it sorted: by text, with
+ * `null` and `undefined` last. The checker prints a union in the order its
+ * members were created, which follows whichever file it happened to check
+ * first, and so differs between runtimes and between the TypeScript and native
+ * inspectors. Everything other than a union's order is left byte for byte.
+ *
+ * A level the scanner cannot split safely (a conditional type, a type
+ * parameter's constraint, a type predicate) keeps its order and only has the
+ * brackets inside it canonicalized. The native inspector's
+ * `typesmap.CanonicalTypeString` is the same algorithm, and both run the cases
+ * in `canonical-type-string.cases.json`.
+ */
+export declare const canonicalTypeString: (type: string) => string;