@pikku/inspector 0.12.103 → 0.12.107

package/dist/add/check-indirect-registrations.js

@@ -0,0 +1,114 @@
+import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+import { MIDDLEWARE_HELPERS, PERMISSION_HELPERS, calleeNames, isNamespaceReceiver, } from '../utils/resolve-callee-name.js';
+const isGateHelper = (name) => MIDDLEWARE_HELPERS.has(name) || PERMISSION_HELPERS.has(name);
+const localNamesCache = new WeakMap();
+/** The names a file can reach a gate helper by: its own, and its import aliases. */
+const localGateNames = (sourceFile) => {
+    const cached = localNamesCache.get(sourceFile);
+    if (cached)
+        return cached;
+    const names = new Set([...MIDDLEWARE_HELPERS, ...PERMISSION_HELPERS]);
+    for (const statement of sourceFile.statements) {
+        const bindings = ts.isImportDeclaration(statement)
+            ? statement.importClause?.namedBindings
+            : undefined;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (isGateHelper((element.propertyName ?? element.name).text)) {
+                names.add(element.name.text);
+            }
+        }
+    }
+    localNamesCache.set(sourceFile, names);
+    return names;
+};
+/**
+ * Whether a reference to a gate helper sits where the inspector already
+ * accounts for it: called directly, imported or re-exported, bound to another
+ * `const` name, named as a declaration, or used as a type.
+ */
+const isAccountedFor = (reference) => {
+    const parent = reference.parent;
+    if (ts.isCallExpression(parent) && parent.expression === reference) {
+        return true;
+    }
+    if (ts.isImportSpecifier(parent) ||
+        ts.isExportSpecifier(parent) ||
+        ts.isImportClause(parent) ||
+        ts.isNamespaceImport(parent) ||
+        ts.isExportAssignment(parent) ||
+        ts.isQualifiedName(parent) ||
+        ts.isTypeNode(parent) ||
+        ts.isExpressionWithTypeArguments(parent)) {
+        return true;
+    }
+    if (ts.isVariableDeclaration(parent) &&
+        parent.initializer === reference &&
+        ts.getCombinedNodeFlags(parent) & ts.NodeFlags.Const) {
+        return true;
+    }
+    if ('name' in parent && parent.name === reference) {
+        return true;
+    }
+    for (let current = parent; current; current = current.parent) {
+        if ((ts.isVariableDeclaration(current) ||
+            ts.isFunctionDeclaration(current)) &&
+            current.name &&
+            ts.isIdentifier(current.name) &&
+            isGateHelper(current.name.text)) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * A middleware or permission helper the inspector can only see by its direct
+ * calls. Passed around as a value — into an array, through a ternary, as an
+ * argument — whatever it registers is invisible to codegen, and a gate that
+ * codegen never imports is a gate that never runs. Say so rather than
+ * generate an app that is silently open.
+ */
+export const checkIndirectRegistrations = (logger, node, checker) => {
+    if (!ts.isIdentifier(node))
+        return;
+    const sourceFile = node.getSourceFile();
+    if (sourceFile.isDeclarationFile)
+        return;
+    if (!localGateNames(sourceFile).has(node.text))
+        return;
+    let reference = node;
+    if (ts.isPropertyAccessExpression(node.parent)) {
+        if (node.parent.name !== node)
+            return;
+        if (!isNamespaceReceiver(node.parent.expression, checker))
+            return;
+        reference = node.parent;
+    }
+    if (isAccountedFor(reference))
+        return;
+    const helper = [...calleeNames(reference, checker)]
+        .reverse()
+        .find(isGateHelper);
+    if (!helper)
+        return;
+    const symbol = checker.getSymbolAtLocation(node);
+    if (symbol?.valueDeclaration && ts.isParameter(symbol.valueDeclaration)) {
+        return;
+    }
+    const type = checker.getTypeAtLocation(reference);
+    if (type.getCallSignatures().length === 0 &&
+        !(type.flags & ts.TypeFlags.Any)) {
+        return;
+    }
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    logger.diagnostic({
+        severity: 'error',
+        code: ErrorCode.REGISTRATION_NOT_A_DIRECT_CALL,
+        message: `'${reference.getText()}' (${helper}) is used as a value at ${sourceFile.fileName}:${line + 1}. ` +
+            `The inspector records middleware and permissions only where ${helper} is called directly, ` +
+            `so whatever this registers is never imported by the generated code and does not run. ` +
+            `Call ${helper}(...) directly.`,
+    });
+};

package/dist/error-codes.d.ts

@@ -20,16 +20,17 @@ export declare enum ErrorCode {
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
     SCENARIO_HAS_SERVICES = "PKU673",
     EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
-    SCENARIO_STEP_NEEDS_ACTOR = "PKU677",
+    SCENARIO_STEP_NEEDS_VIRTUAL_USER = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
     SCENARIO_HAS_NO_ASSERTION = "PKU680",
-    SCENARIO_STEP_PROSE_NAMES_ACTOR = "PKU681",
+    SCENARIO_STEP_PROSE_NAMES_VIRTUAL_USER = "PKU681",
     SCENARIO_HAS_NO_FEATURE = "PKU682",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
     COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
+    SINGLE_STEP_WORKFLOW = "PKU644",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     ADDON_NOT_INSTALLED = "PKU340",
@@ -53,13 +54,14 @@ export declare enum ErrorCode {
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     DUPLICATE_AUTH_DEFINITION = "PKU581",
     AUTH_NOT_EXPORTED = "PKU582",
-    DUPLICATE_PERSONAS_DEFINITION = "PKU585",
+    DUPLICATE_VIRTUAL_USERS_DEFINITION = "PKU585",
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",
     EXPOSED_FUNCTION_HAS_NO_GATE = "PKU574",
     TAG_RESOLVES_TO_NO_MIDDLEWARE = "PKU575",
     PERMISSIONS_IN_BODY_NOT_ALLOWED = "PKU576",
+    REGISTRATION_NOT_A_DIRECT_CALL = "PKU577",
     DUPLICATE_FUNCTION_VERSION = "PKU850",
     DUPLICATE_FUNCTION_NAME = "PKU851",
     MANIFEST_MISSING = "PKU860",

package/dist/error-codes.js

@@ -22,16 +22,17 @@ export var ErrorCode;
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
     ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
     ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
-    ErrorCode["SCENARIO_STEP_NEEDS_ACTOR"] = "PKU677";
+    ErrorCode["SCENARIO_STEP_NEEDS_VIRTUAL_USER"] = "PKU677";
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
-    ErrorCode["SCENARIO_STEP_PROSE_NAMES_ACTOR"] = "PKU681";
+    ErrorCode["SCENARIO_STEP_PROSE_NAMES_VIRTUAL_USER"] = "PKU681";
     ErrorCode["SCENARIO_HAS_NO_FEATURE"] = "PKU682";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
     ErrorCode["COMPLEX_WORKFLOW_NOT_ALLOWED"] = "PKU643";
+    ErrorCode["SINGLE_STEP_WORKFLOW"] = "PKU644";
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
@@ -65,7 +66,7 @@ export var ErrorCode;
     // scopes and roles held this rule until the generated `admin` tree made it
     // unsatisfiable, and get it back once `admin` is a default scope nobody
     // declares. Do not reuse those two numbers for anything else.
-    ErrorCode["DUPLICATE_PERSONAS_DEFINITION"] = "PKU585";
+    ErrorCode["DUPLICATE_VIRTUAL_USERS_DEFINITION"] = "PKU585";
     // HTTP Route errors
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";
@@ -73,6 +74,7 @@ export var ErrorCode;
     ErrorCode["EXPOSED_FUNCTION_HAS_NO_GATE"] = "PKU574";
     ErrorCode["TAG_RESOLVES_TO_NO_MIDDLEWARE"] = "PKU575";
     ErrorCode["PERMISSIONS_IN_BODY_NOT_ALLOWED"] = "PKU576";
+    ErrorCode["REGISTRATION_NOT_A_DIRECT_CALL"] = "PKU577";
     // Versioning errors
     ErrorCode["DUPLICATE_FUNCTION_VERSION"] = "PKU850";
     ErrorCode["DUPLICATE_FUNCTION_NAME"] = "PKU851";

package/dist/finalize.d.ts

@@ -0,0 +1,10 @@
+import type { InspectorState, InspectorLogger, InspectorOptions } from './types.js';
+export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
+export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
+/**
+ * The checker-free half of an inspection: everything that derives from the
+ * state analysis produced. It never loads `typescript`, so it runs the same
+ * against a live analysis and against a state deserialized from another
+ * engine.
+ */
+export declare const finalizeInspectorState: <S extends Omit<InspectorState, "typesLookup">>(logger: InspectorLogger, analyzed: S, options?: InspectorOptions) => Promise<S>;

package/dist/finalize.js

@@ -0,0 +1,102 @@
+import { performance } from 'perf_hooks';
+import { applyDeclaredScopes } from './utils/apply-declared-scopes.js';
+import { getFilesAndMethods } from './utils/get-files-and-methods.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validateVirtualUserRoles, 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 { validateSingleStepWorkflows } from './utils/validate-single-step-workflows.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 { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
+import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
+import { loadAddonSchemas } from './utils/load-addon-functions-meta.js';
+import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
+export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
+/**
+ * The checker-free half of an inspection: everything that derives from the
+ * state analysis produced. It never loads `typescript`, so it runs the same
+ * against a live analysis and against a state deserialized from another
+ * engine.
+ */
+export const finalizeInspectorState = async (logger, analyzed, options = {}) => {
+    const state = analyzed;
+    if (!options.setupOnly) {
+        if (options.schemaConfig) {
+            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, state);
+        registerDerivedOAuth2AppSecrets(state);
+        validateSecretUsage(logger, state);
+        computeDiagnostics(state);
+        validateSchemaWiringSeparation(logger, state);
+        validateWorkflowGraphAddons(logger, state);
+        validateSingleStepWorkflows(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);
+        validateVirtualUserRoles(logger, state);
+        logger.endValidationPass?.();
+    }
+    return analyzed;
+};

package/dist/index.d.ts

@@ -1,17 +1,20 @@
-export { inspect, getInitialInspectorState } from './inspector.js';
+export { inspect, analyzeProgram } from './inspector.js';
+export { getInitialInspectorState } from './initial-state.js';
+export { finalizeInspectorState } from './finalize.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, ScreensManifestMeta, AddonScreenMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, ScreensManifestMeta, AddonScreenMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorServiceTypes, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
-export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
+export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
 export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
 export type { ScenarioInstrumentationFunction } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
-export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { generateCustomTypes, customTypeNames, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export type { GenerateCustomTypesOptions } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
 export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
@@ -19,11 +22,10 @@ export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionMani
 export type { InspectorFeature, InspectorFeatureEntry } from './types.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
-export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';
+export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
 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';
 export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
 export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/index.js

@@ -1,18 +1,19 @@
-export { inspect, getInitialInspectorState } from './inspector.js';
+export { inspect, analyzeProgram } from './inspector.js';
+export { getInitialInspectorState } from './initial-state.js';
+export { finalizeInspectorState } from './finalize.js';
 export { ErrorCode } from './error-codes.js';
-export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.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 { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { generateCustomTypes, customTypeNames, 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/index.js';
+export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.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';
 export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
 export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/initial-state.d.ts

@@ -0,0 +1,7 @@
+import type { InspectorState } from './types.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 declare function getInitialInspectorState(rootDir: string): InspectorState;

package/dist/initial-state.js

@@ -0,0 +1,216 @@
+import { TypesMap } from './types-map.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(),
+        },
+        virtualUsers: {
+            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: {},
+            global: [],
+        },
+        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,
+    };
+}

package/dist/inspector.d.ts

@@ -1,8 +1,10 @@
 import type { InspectorState, InspectorLogger, InspectorOptions } from './types.js';
+import { getInitialInspectorState } from './initial-state.js';
+export { getInitialInspectorState };
 /**
- * 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
+ * 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 declare function getInitialInspectorState(rootDir: string): InspectorState;
+export declare const analyzeProgram: (logger: InspectorLogger, routeFiles: string[], options?: InspectorOptions) => Promise<InspectorState>;
 export declare const inspect: (logger: InspectorLogger, routeFiles: string[], options?: InspectorOptions) => Promise<InspectorState>;