@pikku/inspector 0.12.103 → 0.12.107

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/add-virtual-users.d.ts

@@ -0,0 +1,13 @@
+import type { AddWiring } from '../types.js';
+/**
+ * Inspector for `defineVirtualUsers()` calls.
+ *
+ * A virtual user is entirely declaration — a person, their roles, what they want —
+ * so there is no code body and nothing to resolve at runtime. What is read here
+ * is the whole thing, and it is generated straight to `virtual-users.gen.json` for
+ * the CLI and the console to read without loading the app.
+ *
+ * `name` is the one field that cannot be defaulted. A virtual user without one is
+ * not a person, and the console has nothing to show.
+ */
+export declare const addVirtualUsers: AddWiring;

package/dist/add/{add-personas.js → add-virtual-users.js}

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { DISPOSITIONS } from '@pikku/core/virtual-user';
-import { isRunnablePersona } from '@pikku/core/persona';
+import { isRunnableVirtualUser } from '@pikku/core/virtual-user';
 import { ErrorCode } from '../error-codes.js';
 import { claimSingleDeclaration } from '../utils/single-declaration.js';
 import { booleanProperty, getProperty, numberProperty, stringArrayProperty, stringProperty, unwrapAs, } from '../utils/literal-properties.js';
@@ -15,7 +15,7 @@ const RATES = [
  *
  * The ranges are checked here rather than at run time because these are the
  * kind of typo that does not throw: `repeatRate: 18` meaning 18% would silently
- * double every call the persona makes, and you would read the run as a product
+ * double every call the virtual user makes, and you would read the run as a product
  * bug.
  */
 const tuningProperty = (config, onError) => {
@@ -72,7 +72,7 @@ const accountProperty = (value) => {
     const provider = stringProperty(value, 'provider');
     return provider === undefined ? {} : { provider };
 };
-const linkedAccountsProperty = (config, personaId, logger) => {
+const linkedAccountsProperty = (config, virtualUserId, logger) => {
     const value = getProperty(config, 'linkedAccounts');
     if (!value || !ts.isObjectLiteralExpression(value)) {
         return undefined;
@@ -83,12 +83,12 @@ const linkedAccountsProperty = (config, personaId, logger) => {
             continue;
         }
         if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
-            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, `Persona '${personaId}' has a linked account whose key is not a literal.`);
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, `VirtualUser '${virtualUserId}' has a linked account whose key is not a literal.`);
             continue;
         }
         const account = accountProperty(prop.initializer);
         if (!account) {
-            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${personaId}' linked account '${prop.name.text}' must be an object literal.`);
+            logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${virtualUserId}' linked account '${prop.name.text}' must be an object literal.`);
             continue;
         }
         accounts[prop.name.text] = account;
@@ -96,22 +96,22 @@ const linkedAccountsProperty = (config, personaId, logger) => {
     return Object.keys(accounts).length ? accounts : undefined;
 };
 /**
- * Inspector for `definePersonas()` calls.
+ * Inspector for `defineVirtualUsers()` calls.
  *
- * A persona is entirely declaration — a person, their roles, what they want —
+ * A virtual user is entirely declaration — a person, their roles, what they want —
  * so there is no code body and nothing to resolve at runtime. What is read here
- * is the whole thing, and it is generated straight to `personas.gen.json` for
+ * is the whole thing, and it is generated straight to `virtual-users.gen.json` for
  * the CLI and the console to read without loading the app.
  *
- * `name` is the one field that cannot be defaulted. A persona without one is
+ * `name` is the one field that cannot be defaulted. A virtual user without one is
  * not a person, and the console has nothing to show.
  */
-export const addPersonas = (logger, node, _checker, state) => {
+export const addVirtualUsers = (logger, node, _checker, state) => {
     if (!ts.isCallExpression(node)) {
         return;
     }
     const expression = node.expression;
-    if (!ts.isIdentifier(expression) || expression.text !== 'definePersonas') {
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineVirtualUsers') {
         return;
     }
     const firstArg = node.arguments[0];
@@ -120,11 +120,11 @@ export const addPersonas = (logger, node, _checker, state) => {
     }
     const unwrapped = unwrapAs(firstArg);
     if (!ts.isObjectLiteralExpression(unwrapped)) {
-        logger.critical(ErrorCode.INVALID_VALUE, 'definePersonas() needs an inline object — personas are read statically, never evaluated.');
+        logger.critical(ErrorCode.INVALID_VALUE, 'defineVirtualUsers() needs an inline object — virtual users are read statically, never evaluated.');
         return;
     }
     const sourceFile = node.getSourceFile().fileName;
-    if (!claimSingleDeclaration(logger, state.personas.files, ErrorCode.DUPLICATE_PERSONAS_DEFINITION, 'definePersonas', sourceFile)) {
+    if (!claimSingleDeclaration(logger, state.virtualUsers.files, ErrorCode.DUPLICATE_VIRTUAL_USERS_DEFINITION, 'defineVirtualUsers', sourceFile)) {
         return;
     }
     const known = Object.keys(DISPOSITIONS);
@@ -133,46 +133,46 @@ export const addPersonas = (logger, node, _checker, state) => {
             continue;
         }
         if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
-            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A persona is declared with a key that is not a literal.');
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A virtual user is declared with a key that is not a literal.');
             continue;
         }
         const id = prop.name.text;
         if (!ts.isObjectLiteralExpression(prop.initializer)) {
-            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' must be an object literal.`);
+            logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${id}' must be an object literal.`);
             continue;
         }
         const config = prop.initializer;
         const name = stringProperty(config, 'name');
         if (!name) {
-            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' needs a literal 'name' — a persona is a person, and the console has nothing to show without one.`);
+            logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${id}' needs a literal 'name' — a virtual user is a person, and the console has nothing to show without one.`);
             continue;
         }
-        // The generated `definePersonas` types this as a union, so a bad value only
+        // The generated `defineVirtualUsers` types this as a union, so a bad value only
         // reaches here in source that does not compile. Caught anyway: a
         // disposition is the entire behaviour, and defaulting a typo to `realistic`
         // would run a different person than the one that was written.
         const disposition = stringProperty(config, 'disposition');
         if (disposition !== undefined && !known.includes(disposition)) {
-            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}' has an unknown disposition '${disposition}'. One of: ${known.join(', ')}`);
+            logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${id}' has an unknown disposition '${disposition}'. One of: ${known.join(', ')}`);
             continue;
         }
         let tuningFailed = false;
         const tuning = tuningProperty(config, (message) => {
             tuningFailed = true;
-            logger.critical(ErrorCode.INVALID_VALUE, `Persona '${id}': ${message}`);
+            logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${id}': ${message}`);
         });
         if (tuningFailed) {
             continue;
         }
         const account = accountProperty(getProperty(config, 'account'));
         const declaredRunnable = booleanProperty(config, 'runnable');
-        const persona = {
+        const virtualUser = {
             id,
             name,
             roles: stringArrayProperty(config, 'roles') ?? [],
             goals: stringArrayProperty(config, 'goals') ?? [],
             tags: stringArrayProperty(config, 'tags') ?? [],
-            runnable: isRunnablePersona({
+            runnable: isRunnableVirtualUser({
                 ...(declaredRunnable !== undefined
                     ? { runnable: declaredRunnable }
                     : {}),
@@ -182,38 +182,38 @@ export const addPersonas = (logger, node, _checker, state) => {
         };
         const jobTitle = stringProperty(config, 'jobTitle');
         if (jobTitle !== undefined)
-            persona.jobTitle = jobTitle;
+            virtualUser.jobTitle = jobTitle;
         const description = stringProperty(config, 'description');
         if (description !== undefined)
-            persona.description = description;
+            virtualUser.description = description;
         const avatarUrl = stringProperty(config, 'avatarUrl');
         if (avatarUrl !== undefined)
-            persona.avatarUrl = avatarUrl;
+            virtualUser.avatarUrl = avatarUrl;
         const personality = stringProperty(config, 'personality');
         if (personality !== undefined)
-            persona.personality = personality;
+            virtualUser.personality = personality;
         const app = stringProperty(config, 'app');
         if (app !== undefined)
-            persona.app = app;
+            virtualUser.app = app;
         if (disposition !== undefined) {
-            persona.disposition = disposition;
+            virtualUser.disposition = disposition;
         }
         if (tuning !== undefined)
-            persona.tuning = tuning;
+            virtualUser.tuning = tuning;
         const fixtures = stringArrayProperty(config, 'fixtures');
         if (fixtures !== undefined)
-            persona.fixtures = fixtures;
+            virtualUser.fixtures = fixtures;
         // Left absent rather than resolved here: "everywhere but production" is a
         // fact about the config, and the inspector has no business baking today's
         // environment list into a meta file that outlives it.
         const environments = stringArrayProperty(config, 'environments');
         if (environments !== undefined)
-            persona.environments = environments;
+            virtualUser.environments = environments;
         if (account !== undefined)
-            persona.account = account;
+            virtualUser.account = account;
         const linkedAccounts = linkedAccountsProperty(config, id, logger);
         if (linkedAccounts !== undefined)
-            persona.linkedAccounts = linkedAccounts;
-        state.personas.definitions.push(persona);
+            virtualUser.linkedAccounts = linkedAccounts;
+        state.virtualUsers.definitions.push(virtualUser);
     }
 };

package/dist/add/add-workflow.js

@@ -1,11 +1,12 @@
 import * as ts from 'typescript';
+import { relative } from 'node:path';
 import { extractFunctionName } from '../utils/extract-function-name.js';
 import { extractFunctionNode } from '../utils/extract-function-node.js';
 import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral, isStringLike, isFunctionLike, extractDescription, extractDuration, } from '../utils/extract-node-value.js';
 import { getCommonWireMetaData, getPropertyValue, } from '../utils/get-property-value.js';
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js';
-import { getSourceText, extractActorFromOptions, } from '../utils/workflow/dsl/patterns.js';
+import { getSourceText, extractVirtualUserFromOptions, } from '../utils/workflow/dsl/patterns.js';
 /**
  * Extract a workflow step's display name without letting a non-static name
  * (e.g. a function call) abort the scan. The step name is cosmetic, so a
@@ -141,7 +142,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             type: 'rpc',
                             stepName,
                             rpcName,
-                            actor: extractActorFromOptions(optionsArg),
+                            virtualUser: extractVirtualUserFromOptions(optionsArg),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -164,7 +165,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             stepName,
                             rpcName,
                             expectEventually: true,
-                            actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+                            virtualUser: extractVirtualUserFromOptions(args.length >= 5 ? args[4] : undefined),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -229,7 +230,7 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         wrapperType = 'complex';
     }
     else if (expression.text === 'pikkuScenario') {
-        // A scenario is a complex workflow whose steps run as actors over the
+        // A scenario is a complex workflow whose steps run as virtual users over the
         // real transport — same extraction rules as complex, distinct meta.
         wrapperType = 'scenario';
     }
@@ -243,7 +244,10 @@ export const addWorkflow = (logger, node, checker, state, options) => {
     const { pikkuFuncId, name, exportedName } = extractFunctionName(node, checker, state.rootDir);
     const workflowName = exportedName || name;
     if (!workflowName) {
-        logger.critical(ErrorCode.MISSING_NAME, `Could not determine workflow name from export.`);
+        const sourceFile = node.getSourceFile();
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        logger.critical(ErrorCode.MISSING_NAME, `Could not determine workflow name from export at ${relative(state.rootDir, sourceFile.fileName)}:${line + 1}. ` +
+            `Assign the \`${expression.text}(...)\` call to an exported const; that name is how it is registered.`);
         return;
     }
     // Extract the function node (either direct function or from config.func)
@@ -358,11 +362,11 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         const sink = steps.length > 0 ? [] : steps;
         getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink);
     }
-    // Actor names the flow's steps run as (scenarios) — powers the console
-    // personas view and the Scenario graph badges.
-    const actorNames = [
+    // Virtual user names the flow's steps run as (scenarios) — powers the console
+    // virtual users view and the Scenario graph badges.
+    const virtualUserNames = [
         ...new Set(steps
-            .map((s) => ('actor' in s ? s.actor : undefined))
+            .map((s) => ('virtualUser' in s ? s.virtualUser : undefined))
             .filter((a) => typeof a === 'string')),
     ];
     state.workflows.meta[workflowName] = {
@@ -380,7 +384,7 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         skip,
         scenario: wrapperType === 'scenario' ? true : undefined,
         asserts,
-        actors: actorNames.length > 0 ? actorNames : undefined,
+        virtualUsers: virtualUserNames.length > 0 ? virtualUserNames : undefined,
     };
     // The scenario "logger/config only" rule (PKU673) and the implicit
     // workflow platform-service injection both used to live here, reading

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;