@pikku/inspector 0.12.46 → 0.12.48

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';
+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';

package/dist/inspector.js

@@ -1,12 +1,12 @@
 import * as ts from 'typescript';
 import { performance } from 'perf_hooks';
-import { resolve } from 'path';
+import { dirname, 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 { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/internal';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
@@ -86,6 +86,7 @@ export function getInitialInspectorState(rootDir) {
             files: new Map(),
             graphMeta: {},
             graphFiles: new Map(),
+            featureFiles: new Map(),
             invokedWorkflows: new Set(),
         },
         rpc: {
@@ -204,9 +205,43 @@ export function getInitialInspectorState(rootDir) {
         program: null,
     };
 }
+/**
+ * The path mappings the inspector's program has to share with the project.
+ *
+ * The inspector builds its own program rather than reusing the project's, which
+ * is what keeps a cold run affordable — but a project that reaches its generated
+ * code through a tsconfig `paths` entry resolves that import through those
+ * mappings and nothing else. Without them the factory an inspected function is
+ * passed to resolves to `any`, so a function whose input type comes from the
+ * factory's contextual type (rather than an explicit generic or a named schema)
+ * silently records no input at all.
+ *
+ * Only resolution keys are copied. Type-inference options such as `strict` stay
+ * the inspector's own, because changing those would change the recorded types.
+ */
+const readProjectPathMappings = (logger, tsconfig) => {
+    if (!tsconfig) {
+        return {};
+    }
+    const configPath = resolve(tsconfig);
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error || !configFile.config) {
+        logger.debug(`Could not read ${configPath} for path mappings; imports that rely on them will not resolve`);
+        return {};
+    }
+    const { options: projectOptions } = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(configPath));
+    const { baseUrl, paths, rootDirs, pathsBasePath } = projectOptions;
+    return {
+        ...(baseUrl !== undefined ? { baseUrl } : {}),
+        ...(paths !== undefined ? { paths } : {}),
+        ...(rootDirs !== undefined ? { rootDirs } : {}),
+        ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
+    };
+};
 export const inspect = async (logger, routeFiles, options = {}) => {
     const normalizedRouteFiles = routeFiles.map((file) => resolve(file));
     const compilerOptions = {
+        ...readProjectPathMappings(logger, options.tsconfig),
         target: ts.ScriptTarget.ESNext,
         module: ts.ModuleKind.Node16,
         skipLibCheck: true,
@@ -310,6 +345,8 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);
         validateWorkflowGraphAddons(logger, state);
+        validateScenarioServices(logger, state);
+        validateScenarioSteps(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'));
         }

package/dist/types.d.ts

@@ -205,6 +205,12 @@ export type InspectorOptions = Partial<{
     rootDir: string;
     isAddon: boolean;
     sourceFile: ts.SourceFile;
+    /**
+     * The project's tsconfig, read for its path mappings only. The inspector's
+     * program needs them to resolve imports the project reaches through `paths`;
+     * unlike `schemaConfig.tsconfig` this is also needed on a setup-only run.
+     */
+    tsconfig: string;
     types: Partial<{
         configFileType: string;
         userSessionType: string;
@@ -346,6 +352,34 @@ export interface AuthDefinition {
      */
     services: FunctionServicesMeta;
 }
+/** One statically resolved entry of a feature's `scenarios` array. */
+export interface InspectorFeatureEntry {
+    /** The scenario's declared export name, with any import alias followed back. */
+    scenario: string;
+    /** A `{ scenario, data }` entry's literal data — gherkin's `Examples:`. */
+    data?: unknown;
+}
+/** A `pikkuFeature` export, as far as it can be read from the source. */
+export interface InspectorFeature {
+    path: string;
+    exportedName: string;
+    name?: string;
+    description?: string;
+    tags?: string[];
+    entries: InspectorFeatureEntry[];
+    /**
+     * Entries that are not literal — a spread, a `.map()`, a call. Counted rather
+     * than dropped so the console can say the listing is partial instead of
+     * quietly showing a short feature.
+     */
+    unresolvedEntries: number;
+    /**
+     * Feature hooks run once around the whole group, never per scenario, and are
+     * runtime-only — so only their presence is recorded.
+     */
+    hasBefore: boolean;
+    hasAfter: boolean;
+}
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
@@ -395,6 +429,15 @@ export interface InspectorState {
             path: string;
             exportedName: string;
         }>;
+        /**
+         * `pikkuFeature` exports, keyed by export identifier.
+         *
+         * Everything the config states literally is extracted here, because a
+         * feature is the document structure the console renders. Entries built by
+         * an ordinary loop cannot be enumerated statically — those are counted in
+         * `unresolvedEntries` and resolved at runtime by object identity instead.
+         */
+        featureFiles: Map<string, InspectorFeature>;
         invokedWorkflows: Set<string>;
     };
     rpc: {

package/dist/utils/extract-function-name.js

@@ -28,6 +28,32 @@ export function funcIdToTypeName(id) {
         .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
         .join('');
 }
+/**
+ * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
+ * scenarios reference a step by that string, so it must become the pikkuFuncId
+ * (and hence the generated step map's key), not just a cosmetic label the way
+ * `pikkuMiddleware`/`pikkuAgent` use it.
+ */
+function extractScenarioStepName(callExpr, result) {
+    if (!ts.isCallExpression(callExpr) ||
+        !ts.isIdentifier(callExpr.expression) ||
+        callExpr.expression.text !== 'pikkuScenarioStep') {
+        return;
+    }
+    const firstArg = callExpr.arguments[0];
+    if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) {
+        return;
+    }
+    for (const prop of firstArg.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === 'name' &&
+            ts.isStringLiteral(prop.initializer)) {
+            result.explicitName = prop.initializer.text;
+            return;
+        }
+    }
+}
 export function extractFunctionName(callExpr, checker, rootDir) {
     const parent = callExpr.parent;
     // Initialize the result
@@ -40,6 +66,7 @@ export function extractFunctionName(callExpr, checker, rootDir) {
         isHelper: false,
         version: null,
     };
+    extractScenarioStepName(callExpr, result);
     const workflowHelpers = new Set([
         'workflow',
         'workflowStart',

package/dist/utils/post-process.d.ts

@@ -50,6 +50,32 @@ export declare function computeMiddlewareGroupsMeta(state: InspectorState): void
 export declare function computePermissionsGroupsMeta(state: InspectorState): void;
 export declare function computeRequiredSchemas(state: InspectorState, options: InspectorOptions): void;
 export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
+ * renderers): the func may only destructure logger/config — everything else
+ * must go through actor steps so the flow runs against the TARGET
+ * environment, never local services.
+ *
+ * This runs in post-processing rather than in `addWorkflow` because
+ * `addWorkflow` runs in the `visitSetup` pass, which completes before
+ * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
+ * the check read `undefined` there and never fired.
+ */
+export declare function validateScenarioServices(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Walk every scenario step, wherever it is nested, and validate the two things
+ * that can only be known once both the workflow meta and the function meta
+ * exist:
+ *
+ * - the step target must be a static string literal (PKU678) — otherwise it
+ *   can't be bundled, typed or drawn;
+ * - a `browser: true` step must be given an actor (PKU677), since the browser
+ *   context signs in as that persona.
+ *
+ * It also marks the step's function as used, so `scenario run` boots the
+ * singletons the step actually needs.
+ */
+export declare function validateScenarioSteps(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/post-process.js

@@ -4,6 +4,7 @@ import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
+import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -120,6 +121,19 @@ export function aggregateRequiredServices(state) {
             addServices(funcMeta.services);
         }
     });
+    // 1b. Services the auth factory touches, read from the definition rather than
+    // from the generated handler.
+    //
+    // `stampAuthHandlerServices` copies them onto that handler's meta, but on the
+    // first run in a clean checkout the handler's file has not been written yet,
+    // so there is nothing to stamp and nothing to aggregate — and the services map
+    // comes out claiming `kysely` (or whatever else `authorize` reads) is unused.
+    // The second run, with the file on disk, says the opposite. The definition is
+    // inspected from hand-written source either way, so taking the answer from
+    // there makes a clean build agree with an incremental one.
+    if (state.auth?.definition) {
+        addServices(state.auth.definition.services);
+    }
     // 2. Services from used middleware (individual + groups)
     usedMiddleware.forEach((middlewareName) => {
         const middlewareMeta = state.middleware.definitions[middlewareName];
@@ -539,6 +553,90 @@ export function validateAgentModels(logger, state) {
         }
     }
 }
+/**
+ * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
+ * renderers): the func may only destructure logger/config — everything else
+ * must go through actor steps so the flow runs against the TARGET
+ * environment, never local services.
+ *
+ * This runs in post-processing rather than in `addWorkflow` because
+ * `addWorkflow` runs in the `visitSetup` pass, which completes before
+ * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
+ * the check read `undefined` there and never fired.
+ */
+export function validateScenarioServices(logger, state) {
+    for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        if (!meta.scenario)
+            continue;
+        const funcMeta = state.functions.meta[meta.pikkuFuncId];
+        if (!funcMeta?.services)
+            continue;
+        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
+        if (disallowed.length > 0) {
+            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+                `Scenarios may only use 'logger'/'config' — drive everything else through ` +
+                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+                `runs against the target environment.`);
+        }
+    }
+}
+/**
+ * Walk every scenario step, wherever it is nested, and validate the two things
+ * that can only be known once both the workflow meta and the function meta
+ * exist:
+ *
+ * - the step target must be a static string literal (PKU678) — otherwise it
+ *   can't be bundled, typed or drawn;
+ * - a `browser: true` step must be given an actor (PKU677), since the browser
+ *   context signs in as that persona.
+ *
+ * It also marks the step's function as used, so `scenario run` boots the
+ * singletons the step actually needs.
+ */
+export function validateScenarioSteps(logger, state) {
+    const visit = (workflowName, steps) => {
+        for (const step of steps) {
+            if (step.type === 'scenarioStep') {
+                if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
+                    logger.critical(ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC, `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
+                        `A step target must be statically resolvable so it can be bundled, typed and drawn — ` +
+                        `loop over data sets instead of computing the step name.`);
+                    continue;
+                }
+                state.serviceAggregation.usedFunctions.add(step.stepFunc);
+                const stepMeta = state.functions.meta[step.stepFunc];
+                if (stepMeta?.scenarioStepBrowser && !step.actor) {
+                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls browser step '${step.stepFunc}' without an actor. ` +
+                        `Pass { actor: actors.<name> } so the browser context signs in as that persona.`);
+                }
+                continue;
+            }
+            if (step.type === 'branch') {
+                for (const branch of step.branches)
+                    visit(workflowName, branch.steps);
+                if (step.elseSteps)
+                    visit(workflowName, step.elseSteps);
+            }
+            else if (step.type === 'switch') {
+                for (const c of step.cases ?? []) {
+                    if (c.steps)
+                        visit(workflowName, c.steps);
+                }
+                if (step.defaultSteps)
+                    visit(workflowName, step.defaultSteps);
+            }
+            else if (step.type === 'fanout' && step.body) {
+                visit(workflowName, step.body);
+            }
+            else if (step.type === 'parallel' && step.children) {
+                visit(workflowName, step.children);
+            }
+        }
+    };
+    for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        visit(workflowName, meta.steps ?? []);
+    }
+}
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/serialize-inspector-state.d.ts

@@ -1,5 +1,5 @@
 import type { JSONValue } from '@pikku/core';
-import type { InspectorDiagnostic, InspectorState } from '../types.js';
+import type { InspectorDiagnostic, InspectorFeature, InspectorState } from '../types.js';
 /**
  * Serializable version of InspectorState that can be saved to JSON
  * Omits typesLookup (contains non-serializable ts.Type objects) and converts Maps/Sets to arrays
@@ -160,6 +160,7 @@ export interface SerializableInspectorState {
             path: string;
             exportedName: string;
         }]>;
+        featureFiles: Array<[string, InspectorFeature]>;
         invokedWorkflows: string[];
     };
     rpc: {

package/dist/utils/serialize-inspector-state.js

@@ -69,6 +69,7 @@ export function serializeInspectorState(state) {
             files: Array.from(state.workflows.files.entries()),
             graphMeta: state.workflows.graphMeta,
             graphFiles: Array.from(state.workflows.graphFiles.entries()),
+            featureFiles: Array.from(state.workflows.featureFiles.entries()),
             invokedWorkflows: Array.from(state.workflows.invokedWorkflows),
         },
         rpc: {
@@ -232,6 +233,7 @@ export function deserializeInspectorState(data) {
             files: new Map(data.workflows.files),
             graphMeta: data.workflows.graphMeta || {},
             graphFiles: new Map(data.workflows.graphFiles || []),
+            featureFiles: new Map(data.workflows.featureFiles || []),
             invokedWorkflows: new Set(data.workflows.invokedWorkflows || []),
         },
         rpc: {