@pikku/inspector 0.12.106 → 0.12.108

package/dist/add/add-permission.js

@@ -1,14 +1,16 @@
 import * as ts from 'typescript';
-import { extractFunctionName } from '../utils/extract-function-name.js';
+import { relative } from 'node:path';
+import { extractFunctionName, isNamedExport, makeContextBasedId, } from '../utils/extract-function-name.js';
 import { extractServicesFromFunction, extractUsedWires, } from '../utils/extract-services.js';
 import { getPropertyValue } from '../utils/get-property-value.js';
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js';
-function isInsidePermissionContainer(node) {
+import { PERMISSION_HELPERS, resolveCalleeName, } from '../utils/resolve-callee-name.js';
+function isInsidePermissionContainer(node, checker) {
     let current = node.parent;
     while (current) {
         if (ts.isCallExpression(current) &&
-            ts.isIdentifier(current.expression) &&
-            current.expression.text === 'pikkuPermissionFactory') {
+            resolveCalleeName(current, checker, PERMISSION_HELPERS) ===
+                'pikkuPermissionFactory') {
             return true;
         }
         current = current.parent;
@@ -16,20 +18,144 @@ function isInsidePermissionContainer(node) {
     return false;
 }
 /**
- * Inspect pikkuPermission, pikkuAuth, and pikkuPermissionFactory definitions.
+ * The id of a permission written inline in an `addGlobalPermission([...])`
+ * array, which has no variable to be named after. Derived from where it sits,
+ * so the registration and the definition agree on it without either having to
+ * be visited first.
  */
+function inlineGlobalPermissionId(node, checker, rootDir) {
+    const array = node.parent;
+    if (!array || !ts.isArrayLiteralExpression(array))
+        return undefined;
+    const call = array.parent;
+    if (!call ||
+        !ts.isCallExpression(call) ||
+        call.arguments[0] !== array ||
+        resolveCalleeName(call, checker, PERMISSION_HELPERS) !==
+            'addGlobalPermission') {
+        return undefined;
+    }
+    const sourceFile = node.getSourceFile();
+    return makeContextBasedId('global', 'permission', relative(rootDir, sourceFile.fileName), String(node.getStart()));
+}
+const unwrapExpression = (expression) => {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isNonNullExpression(current) ||
+        ts.isTypeAssertionExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+};
+/**
+ * Follows `addGlobalPermission`'s argument to the array or object literal it was
+ * written as: a literal itself, or a `const` (declared here or imported) that is
+ * initialised with one. `undefined` when it is built any other way.
+ */
+const resolvePermissionLiteral = (argument, checker) => {
+    let current = unwrapExpression(argument);
+    for (let hops = 0; hops < 8; hops++) {
+        if (ts.isArrayLiteralExpression(current) ||
+            ts.isObjectLiteralExpression(current)) {
+            return current;
+        }
+        if (!ts.isIdentifier(current))
+            return undefined;
+        let symbol = checker.getSymbolAtLocation(current);
+        if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+            symbol = checker.getAliasedSymbol(symbol);
+        }
+        const declaration = symbol?.valueDeclaration;
+        if (!declaration ||
+            !ts.isVariableDeclaration(declaration) ||
+            !declaration.initializer) {
+            return undefined;
+        }
+        current = unwrapExpression(declaration.initializer);
+    }
+    return undefined;
+};
+const isNamedExportedFunction = (declaration, checker) => {
+    if (!declaration.name)
+        return false;
+    const flags = ts.getCombinedModifierFlags(declaration);
+    if (flags & ts.ModifierFlags.Default)
+        return false;
+    if (flags & ts.ModifierFlags.Export)
+        return true;
+    const moduleSymbol = checker.getSymbolAtLocation(declaration.getSourceFile());
+    const symbol = checker.getSymbolAtLocation(declaration.name);
+    return (!!moduleSymbol &&
+        !!symbol &&
+        checker.getExportsOfModule(moduleSymbol).some((exported) => {
+            const resolved = exported.flags & ts.SymbolFlags.Alias
+                ? checker.getAliasedSymbol(exported)
+                : exported;
+            return resolved === symbol;
+        }));
+};
+const isImmediatelyInvoked = (fn) => {
+    let current = fn;
+    while (current.parent && ts.isParenthesizedExpression(current.parent)) {
+        current = current.parent;
+    }
+    return (!!current.parent &&
+        ts.isCallExpression(current.parent) &&
+        current.parent.expression === current);
+};
+/**
+ * How the generated permissions file makes this `addGlobalPermission` call run.
+ * Importing a file only evaluates its top level, so a call at the top level (or
+ * in a function invoked right where it is written) runs on import. A call inside
+ * an exported zero-argument function runs when the generated file calls that
+ * function. Anywhere else nothing ever calls it, so the gate would not exist.
+ */
+const globalPermissionActivation = (call, checker) => {
+    let current = call.parent;
+    while (current && !ts.isSourceFile(current)) {
+        if (ts.isArrowFunction(current) ||
+            ts.isFunctionExpression(current) ||
+            ts.isFunctionDeclaration(current) ||
+            ts.isMethodDeclaration(current) ||
+            ts.isConstructorDeclaration(current) ||
+            ts.isGetAccessorDeclaration(current) ||
+            ts.isSetAccessorDeclaration(current)) {
+            if (isImmediatelyInvoked(current)) {
+                current = current.parent;
+                continue;
+            }
+            if (current.parameters.length > 0)
+                return { kind: 'unreachable' };
+            if ((ts.isArrowFunction(current) || ts.isFunctionExpression(current)) &&
+                ts.isVariableDeclaration(current.parent) &&
+                ts.isIdentifier(current.parent.name) &&
+                isNamedExport(current.parent, checker)) {
+                return { kind: 'factory', exportName: current.parent.name.text };
+            }
+            if (ts.isFunctionDeclaration(current) &&
+                current.name &&
+                isNamedExportedFunction(current, checker)) {
+                return { kind: 'factory', exportName: current.name.text };
+            }
+            return { kind: 'unreachable' };
+        }
+        current = current.parent;
+    }
+    return { kind: 'import' };
+};
 export const addPermission = (logger, node, checker, state) => {
     if (!ts.isCallExpression(node))
         return;
-    const { expression, arguments: args } = node;
-    // only handle specific function calls
-    if (!ts.isIdentifier(expression)) {
+    const { arguments: args } = node;
+    const callee = resolveCalleeName(node, checker, PERMISSION_HELPERS);
+    if (!callee)
         return;
-    }
     // Handle pikkuPermission(...) - individual permission function definition
-    if (expression.text === 'pikkuPermission') {
+    if (callee === 'pikkuPermission') {
         // Skip if nested inside pikkuPermissionFactory — the factory handler extracts services itself
-        if (isInsidePermissionContainer(node))
+        if (isInsidePermissionContainer(node, checker))
             return;
         const arg = args[0];
         if (!arg)
@@ -70,9 +196,13 @@ export const addPermission = (logger, node, checker, state) => {
                 pikkuFuncId = node.parent.name.text;
             }
             else {
-                logger.error(`• pikkuPermission() must be assigned to a variable or object property. ` +
-                    `Extract it to a const: const myPermission = pikkuPermission(...)`);
-                return;
+                const globalId = inlineGlobalPermissionId(node, checker, state.rootDir);
+                if (!globalId) {
+                    logger.error(`• pikkuPermission() must be assigned to a variable or object property. ` +
+                        `Extract it to a const: const myPermission = pikkuPermission(...)`);
+                    return;
+                }
+                pikkuFuncId = globalId;
             }
         }
         const dataParam = actualHandler.parameters[1];
@@ -91,8 +221,8 @@ export const addPermission = (logger, node, checker, state) => {
         logger.debug(`• Found permission with services: ${services.services.join(', ')}${name ? ` (name: ${name})` : ''}${description ? ` (description: ${description})` : ''}${!requiresData ? ' (auth-only)' : ''}`);
         return;
     }
-    if (expression.text === 'pikkuAuth') {
-        if (isInsidePermissionContainer(node))
+    if (callee === 'pikkuAuth') {
+        if (isInsidePermissionContainer(node, checker))
             return;
         const arg = args[0];
         if (!arg)
@@ -137,9 +267,13 @@ export const addPermission = (logger, node, checker, state) => {
                 pikkuFuncId = node.parent.name.text;
             }
             else {
-                logger.error(`• pikkuAuth() must be assigned to a variable or object property. ` +
-                    `Extract it to a const: const myAuth = pikkuAuth(...)`);
-                return;
+                const globalId = inlineGlobalPermissionId(node, checker, state.rootDir);
+                if (!globalId) {
+                    logger.error(`• pikkuAuth() must be assigned to a variable or object property. ` +
+                        `Extract it to a const: const myAuth = pikkuAuth(...)`);
+                    return;
+                }
+                pikkuFuncId = globalId;
             }
         }
         state.permissions.definitions[pikkuFuncId] = {
@@ -156,7 +290,7 @@ export const addPermission = (logger, node, checker, state) => {
         return;
     }
     // Handle pikkuPermissionFactory(...) - permission factory function
-    if (expression.text === 'pikkuPermissionFactory') {
+    if (callee === 'pikkuPermissionFactory') {
         const factoryNode = args[0];
         if (!factoryNode)
             return;
@@ -175,8 +309,8 @@ export const addPermission = (logger, node, checker, state) => {
         };
         const findPikkuPermissionCall = (node) => {
             if (ts.isCallExpression(node)) {
-                const expr = node.expression;
-                if (ts.isIdentifier(expr) && expr.text === 'pikkuPermission') {
+                if (resolveCalleeName(node, checker, PERMISSION_HELPERS) ===
+                    'pikkuPermission') {
                     return node;
                 }
             }
@@ -229,4 +363,61 @@ export const addPermission = (logger, node, checker, state) => {
         logger.debug(`• Found permission factory with services: ${services.services.join(', ')}`);
         return;
     }
+    if (callee === 'addGlobalPermission') {
+        const permissionsArg = args[0];
+        const sourceFile = node.getSourceFile().fileName;
+        let entries;
+        const literal = permissionsArg && resolvePermissionLiteral(permissionsArg, checker);
+        if (literal && ts.isArrayLiteralExpression(literal)) {
+            entries = literal.elements;
+        }
+        else if (literal) {
+            entries = literal.properties.flatMap((p) => ts.isPropertyAssignment(p)
+                ? [p.initializer]
+                : ts.isShorthandPropertyAssignment(p)
+                    ? [p.name]
+                    : []);
+        }
+        if (!entries) {
+            logger.warn(`• addGlobalPermission(...) in ${sourceFile} is not given an array or object it can follow to a literal, so the services its permissions use cannot be seen.`);
+        }
+        const definitionIds = (entries ?? []).flatMap((entry) => {
+            if (ts.isIdentifier(entry)) {
+                const { pikkuFuncId } = extractFunctionName(entry, checker, state.rootDir);
+                return [pikkuFuncId.startsWith('__temp_') ? entry.text : pikkuFuncId];
+            }
+            if (ts.isCallExpression(entry)) {
+                const inline = inlineGlobalPermissionId(entry, checker, state.rootDir);
+                if (inline)
+                    return [inline];
+                if (ts.isPropertyAssignment(entry.parent) &&
+                    ts.isIdentifier(entry.parent.name) &&
+                    resolveCalleeName(entry, checker, PERMISSION_HELPERS)) {
+                    return [entry.parent.name.text];
+                }
+                const { pikkuFuncId } = extractFunctionName(entry.expression, checker, state.rootDir);
+                return pikkuFuncId.startsWith('__temp_') &&
+                    ts.isIdentifier(entry.expression)
+                    ? [entry.expression.text]
+                    : [pikkuFuncId];
+            }
+            return [];
+        });
+        const activation = globalPermissionActivation(node, checker);
+        if (activation.kind === 'unreachable') {
+            logger.warn(`• addGlobalPermission(...) in ${sourceFile} sits inside a function that nothing calls: only a call at the top level, or inside an exported function with no parameters, is run by the generated permissions file. This global permission is NOT registered. Export it as \`export const name = () => { addGlobalPermission(...) }\` or move it to the top level.`);
+            return;
+        }
+        const exportName = activation.kind === 'factory' ? activation.exportName : null;
+        const position = node.getStart();
+        if (!state.permissions.global.some((g) => g.sourceFile === sourceFile && g.position === position)) {
+            state.permissions.global.push({
+                sourceFile,
+                position,
+                exportName,
+                definitionIds,
+            });
+        }
+        logger.debug(`• Found global permissions in ${sourceFile}: [${definitionIds.join(', ')}]`);
+    }
 };

package/dist/add/add-scope.d.ts

@@ -1,9 +1,3 @@
 import type { AddWiring } 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: Parameters<AddWiring>[3]) => void;
+export { applyDeclaredScopes } from '../utils/apply-declared-scopes.js';
 export declare const addScope: AddWiring;

package/dist/add/add-scope.js

@@ -111,27 +111,7 @@ const addDeclareScopes = (logger, node, state) => {
     }
     state.scopes.files.add(sourceFile);
 };
-/**
- * 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(SEPARATOR);
-        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] ??= {};
-        }
-    }
-};
+export { applyDeclaredScopes } from '../utils/apply-declared-scopes.js';
 export const addScope = (logger, node, checker, state, _options) => {
     if (!ts.isCallExpression(node)) {
         return;

package/dist/add/check-indirect-registrations.d.ts

@@ -0,0 +1,9 @@
+import type { AddWiring } from '../types.js';
+/**
+ * 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 declare const checkIndirectRegistrations: AddWiring;

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

@@ -61,6 +61,7 @@ export declare enum ErrorCode {
     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

@@ -74,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';