@pikku/inspector 0.12.110 → 0.12.111

package/dist/add/add-channel.js

@@ -129,6 +129,14 @@ export function addMessagesRoutes(logger, obj, state, checker) {
                 chanInit = resolved;
             }
         }
+        // ...or is the defineChannelRoutes call itself, written inline
+        if (ts.isCallExpression(chanInit) &&
+            ts.isIdentifier(chanInit.expression) &&
+            chanInit.expression.text === 'defineChannelRoutes' &&
+            chanInit.arguments[0] &&
+            ts.isObjectLiteralExpression(chanInit.arguments[0])) {
+            chanInit = chanInit.arguments[0];
+        }
         const refContract = resolveRefContract(chanInit, 'refChannel', state.exportedContracts.addonChannel);
         if (refContract) {
             const refChannelKey = getObjectPropertyName(chanElem.name);

package/dist/add/add-file-with-factory.d.ts

@@ -1,3 +1,9 @@
 import * as ts from 'typescript';
-import type { PathToNameAndType, InspectorState } from '../types.js';
+import type { PathToNameAndType, InspectorState, InspectorLogger } from '../types.js';
+/**
+ * A factory binding whose wrapper call sits inside a cast: `as`, `<T>` or `!`.
+ * A cast changes the type the inspector would read, and hides a mismatch the
+ * factory should fix, so it fails the build instead of being seen through.
+ */
+export declare const checkHiddenFactory: (logger: InspectorLogger, node: ts.Node, state: InspectorState) => void;
 export declare const addFileWithFactory: (node: ts.Node, checker: ts.TypeChecker, methods: PathToNameAndType | undefined, expectedTypeName: string, state?: InspectorState) => void;

package/dist/add/add-file-with-factory.js

@@ -1,4 +1,6 @@
 import * as ts from 'typescript';
+import { relative } from 'node:path';
+import { ErrorCode } from '../error-codes.js';
 import { extractServicesFromFunction } from '../utils/extract-services.js';
 // Mapping of wrapper function names to their corresponding types
 const wrapperFunctionMap = {
@@ -10,6 +12,64 @@ const wrapperFunctionMap = {
     pikkuAddonWireServices: 'CreateWireServices',
     pikkuServerLifecycle: 'ServerLifecycle',
 };
+/** How a cast around an expression reads in a diagnostic, or undefined for none. */
+const describeCast = (expression) => {
+    if (ts.isAsExpression(expression)) {
+        return { form: 'an `as` cast', remove: 'the cast' };
+    }
+    if (ts.isTypeAssertionExpression(expression)) {
+        return { form: 'a `<T>` cast', remove: 'the cast' };
+    }
+    if (ts.isNonNullExpression(expression)) {
+        return { form: 'a non-null assertion (`!`)', remove: 'the `!`' };
+    }
+    return undefined;
+};
+/** `satisfies` and parentheses leave the value's type as written, so a factory inside them is read as a direct call. */
+const isTransparent = (expression) => ts.isSatisfiesExpression(expression) ||
+    ts.isParenthesizedExpression(expression);
+const unwrapTransparent = (expression) => {
+    while (isTransparent(expression))
+        expression = expression.expression;
+    return expression;
+};
+/**
+ * A factory binding whose wrapper call sits inside a cast: `as`, `<T>` or `!`.
+ * A cast changes the type the inspector would read, and hides a mismatch the
+ * factory should fix, so it fails the build instead of being seen through.
+ */
+export const checkHiddenFactory = (logger, node, state) => {
+    if (!ts.isVariableDeclaration(node) || !node.initializer)
+        return;
+    let inner = node.initializer;
+    let cast;
+    for (;;) {
+        const found = describeCast(inner);
+        if (found) {
+            cast ??= found;
+            inner = inner
+                .expression;
+        }
+        else if (isTransparent(inner)) {
+            inner = inner.expression;
+        }
+        else {
+            break;
+        }
+    }
+    if (!cast ||
+        !ts.isCallExpression(inner) ||
+        !ts.isIdentifier(inner.expression) ||
+        !wrapperFunctionMap[inner.expression.text]) {
+        return;
+    }
+    const sourceFile = node.getSourceFile();
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const wrapper = inner.expression.text;
+    logger.critical(ErrorCode.FACTORY_NOT_A_DIRECT_CALL, `'${node.name.getText()}' at ${relative(state.rootDir, sourceFile.fileName)}:${line + 1} wraps ${wrapper}(...) in ${cast.form}. ` +
+        `The inspector reads a factory only from a direct ${wrapper}(...) call, so this one would not be registered and nothing it provides would exist at runtime. ` +
+        `Remove ${cast.remove}, and fix the type mismatch it hides in the factory itself.`);
+};
 /**
  * What an addon's services factory takes from the parent: the names
  * destructured off the parameter carrying the parent's bag, either in the
@@ -126,8 +186,9 @@ export const addFileWithFactory = (node, checker, methods = new Map(), expectedT
         const variableName = node.name.getText();
         // Check for wrapper function calls FIRST (e.g., pikkuConfig(...), pikkuServices(...))
         // This handles both cases: with and without explicit type annotations
-        if (node.initializer && ts.isCallExpression(node.initializer)) {
-            const callExpression = node.initializer;
+        const initializer = node.initializer && unwrapTransparent(node.initializer);
+        if (initializer && ts.isCallExpression(initializer)) {
+            const callExpression = initializer;
             const expression = callExpression.expression;
             if (ts.isIdentifier(expression)) {
                 const wrapperFunctionName = expression.text;

package/dist/add/add-functions.js

@@ -40,6 +40,7 @@ import { findPiiPaths } from '../utils/check-pii-output.js';
 import { findClassifiedSinks } from '../utils/check-classified-sinks.js';
 import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 import { resolveCalleeName } from '../utils/resolve-callee-name.js';
+import { readFunctionDisabled, recordDisabledFunction, } from './check-disabled-references.js';
 import { addonZodContractViolation } from '../utils/validate-addon-zod-contract.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
@@ -382,7 +383,23 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (args.length === 0)
         return;
     let { pikkuFuncId, name, explicitName, exportedName } = extractFunctionName(node, checker, state.rootDir);
-    if (!pikkuFuncId || pikkuFuncId.startsWith('__temp_')) {
+    if (!pikkuFuncId)
+        return;
+    // Before the inline (`__temp_`) bail-out: a disabled function defined inline
+    // in a wiring is still used by it, and is refused rather than skipped.
+    const disabled = args[0] && ts.isObjectLiteralExpression(args[0])
+        ? readFunctionDisabled(args[0], name, logger)
+        : null;
+    if (disabled) {
+        recordDisabledFunction(logger, state, node, pikkuFuncId, {
+            name,
+            sourceFile: node.getSourceFile().fileName,
+            ...(exportedName ? { exportedName } : {}),
+            ...disabled,
+        });
+        return;
+    }
+    if (pikkuFuncId.startsWith('__temp_')) {
         return;
     }
     // pikku's own scenario instrumentation, which older projects still carry as a

package/dist/add/add-pikku-studio.d.ts

@@ -0,0 +1,15 @@
+import * as ts from 'typescript';
+import type { InspectorState, InspectorLogger } from '../types.js';
+/**
+ * Detect `pikkuStudio({ title, screens })` and record it as the package's
+ * `studio` metadata. Every field must be a literal: one that is not is
+ * reported and its screen left out, since a screen the host cannot read would
+ * otherwise vanish with no sign.
+ */
+export declare function addPikkuStudio(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;
+/**
+ * The checks on `pikkuStudio` that need the whole package: every title is a
+ * key in the addon's `messages/en.json` (a key missing from another locale is
+ * a warning), and every nav badge names one of the addon's functions.
+ */
+export declare function validatePikkuStudio(logger: InspectorLogger, state: InspectorState): void;

package/dist/add/add-pikku-studio.js

@@ -0,0 +1,307 @@
+import * as ts from 'typescript';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { ErrorCode } from '../error-codes.js';
+const SCOPES = ['studio', 'team', 'project'];
+const NAV_AREAS = ['rail', 'team', 'project', 'account'];
+const propName = (prop) => {
+    if (!ts.isPropertyAssignment(prop))
+        return undefined;
+    return ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : undefined;
+};
+const stringArray = (node) => {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const values = [];
+    for (const element of node.elements) {
+        if (!ts.isStringLiteral(element))
+            return undefined;
+        values.push(element.text);
+    }
+    return values;
+};
+const booleanLiteral = (node) => node.kind === ts.SyntaxKind.TrueKeyword
+    ? true
+    : node.kind === ts.SyntaxKind.FalseKeyword
+        ? false
+        : undefined;
+const oneOf = (node, values) => ts.isStringLiteral(node) && values.includes(node.text)
+    ? node.text
+    : undefined;
+const numberLiteral = (node) => {
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand))
+        return -Number(node.operand.text);
+    return undefined;
+};
+/**
+ * The module specifier of `() => import('./screens/x')`. Anything else cannot
+ * be handed to the host's bundler as a lazy import, so it is not read.
+ */
+const lazyImportSpecifier = (node) => {
+    if (!ts.isArrowFunction(node))
+        return undefined;
+    const body = node.body;
+    if (!ts.isCallExpression(body) ||
+        body.expression.kind !== ts.SyntaxKind.ImportKeyword)
+        return undefined;
+    const [specifier] = body.arguments;
+    return specifier && ts.isStringLiteral(specifier) ? specifier.text : undefined;
+};
+const readNav = (node, fail) => {
+    if (!ts.isObjectLiteralExpression(node)) {
+        fail(`A screen's nav must be an object literal, got: ${node.getText()}`);
+        return undefined;
+    }
+    let area;
+    let icon;
+    let order;
+    let badge;
+    let ok = true;
+    for (const field of node.properties) {
+        const key = propName(field);
+        if (!key || !ts.isPropertyAssignment(field)) {
+            fail(`A screen's nav field must be a literal, got: ${field.getText()}`);
+            ok = false;
+            continue;
+        }
+        const value = field.initializer;
+        let read;
+        if (key === 'area')
+            read = area = oneOf(value, NAV_AREAS);
+        else if (key === 'icon')
+            read = icon = ts.isStringLiteral(value) ? value.text : undefined;
+        else if (key === 'order')
+            read = order = numberLiteral(value);
+        else if (key === 'badge')
+            read = badge = ts.isStringLiteral(value) ? value.text : undefined;
+        else
+            continue;
+        if (read === undefined) {
+            fail(`A screen's nav ${key} must be ${key === 'area' ? `one of ${NAV_AREAS.map((a) => `'${a}'`).join(', ')}` : 'a literal'}, got: ${value.getText()}`);
+            ok = false;
+        }
+    }
+    if (!ok)
+        return undefined;
+    if (!area || icon === undefined || order === undefined) {
+        fail(`A screen's nav needs a literal area, icon and order: ${node.getText()}`);
+        return undefined;
+    }
+    return { area, icon, order, ...(badge !== undefined ? { badge } : {}) };
+};
+const readScreen = (element, fail) => {
+    if (!ts.isObjectLiteralExpression(element)) {
+        fail(`A pikkuStudio screen must be an object literal, got: ${element.getText()}`);
+        return undefined;
+    }
+    let path;
+    let title;
+    let scope;
+    let nav;
+    let replaces;
+    let needsApp;
+    let layout;
+    let scopes;
+    let component;
+    let app;
+    let ok = true;
+    for (const field of element.properties) {
+        const key = propName(field);
+        if (!key || !ts.isPropertyAssignment(field)) {
+            fail(`A screen's field must be a literal, got: ${field.getText()}`);
+            ok = false;
+            continue;
+        }
+        const value = field.initializer;
+        let read;
+        if (key === 'path')
+            read = path = ts.isStringLiteral(value) ? value.text : undefined;
+        else if (key === 'title')
+            read = title = ts.isStringLiteral(value) ? value.text : undefined;
+        else if (key === 'scope')
+            read = scope = oneOf(value, SCOPES);
+        else if (key === 'nav') {
+            nav = readNav(value, fail);
+            if (!nav)
+                ok = false;
+            continue;
+        }
+        else if (key === 'replaces')
+            read = replaces = booleanLiteral(value);
+        else if (key === 'needsApp')
+            read = needsApp = booleanLiteral(value);
+        else if (key === 'layout')
+            read = layout = oneOf(value, ['bare']);
+        else if (key === 'scopes') {
+            read = scopes = stringArray(value);
+            if (!scopes) {
+                fail(`A screen's scopes must be an array of string literals, got: ${value.getText()}`);
+                ok = false;
+                continue;
+            }
+        }
+        else if (key === 'component') {
+            read = component = lazyImportSpecifier(value);
+            if (!component) {
+                fail(`A screen's component must be () => import('<literal>'), got: ${value.getText()}`);
+                ok = false;
+                continue;
+            }
+        }
+        else if (key === 'app')
+            read = app = ts.isStringLiteral(value) ? value.text : undefined;
+        else
+            continue;
+        if (read === undefined) {
+            fail(`A screen's ${key} must be ${key === 'scope' ? `one of ${SCOPES.map((a) => `'${a}'`).join(', ')}` : key === 'layout' ? `'bare'` : 'a literal'}, got: ${value.getText()}`);
+            ok = false;
+        }
+    }
+    if (!ok)
+        return undefined;
+    if (!path || !title || !scope || (!component && !app)) {
+        fail(`A pikkuStudio screen needs a literal path, title and scope, and either a lazy component or an app: ${element.getText()}`);
+        return undefined;
+    }
+    if (component && app) {
+        fail(`Screen '${path}' sets both component and app; a screen is one or the other`);
+        return undefined;
+    }
+    return {
+        path,
+        title,
+        scope,
+        ...(nav ? { nav } : {}),
+        ...(replaces !== undefined ? { replaces } : {}),
+        ...(needsApp !== undefined ? { needsApp } : {}),
+        ...(layout ? { layout } : {}),
+        ...(scopes ? { scopes } : {}),
+        ...(component ? { component } : { app: app }),
+    };
+};
+/**
+ * Detect `pikkuStudio({ title, screens })` and record it as the package's
+ * `studio` metadata. Every field must be a literal: one that is not is
+ * reported and its screen left out, since a screen the host cannot read would
+ * otherwise vanish with no sign.
+ */
+export function addPikkuStudio(node, state, logger) {
+    if (!ts.isCallExpression(node))
+        return;
+    const { expression, arguments: args } = node;
+    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuStudio')
+        return;
+    const [firstArg] = args;
+    if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
+        return;
+    const fail = (message) => logger.critical(ErrorCode.ADDON_SCREENS_NOT_STATIC, message);
+    let title;
+    const screens = [];
+    for (const prop of firstArg.properties) {
+        const key = propName(prop);
+        if (!key || !ts.isPropertyAssignment(prop)) {
+            fail(`A pikkuStudio field must be a literal, got: ${prop.getText()}`);
+            continue;
+        }
+        if (key === 'title') {
+            if (ts.isStringLiteral(prop.initializer)) {
+                title = prop.initializer.text;
+            }
+            else {
+                fail(`pikkuStudio's title must be a literal, got: ${prop.initializer.getText()}`);
+            }
+        }
+        else if (key === 'screens') {
+            if (!ts.isArrayLiteralExpression(prop.initializer)) {
+                fail(`pikkuStudio's screens must be an array literal, got: ${prop.initializer.getText()}`);
+                continue;
+            }
+            for (const element of prop.initializer.elements) {
+                const screen = readScreen(element, fail);
+                if (screen)
+                    screens.push(screen);
+            }
+        }
+    }
+    if (!title) {
+        fail(`pikkuStudio needs a literal title`);
+        return;
+    }
+    const seen = new Set();
+    for (const screen of screens) {
+        if (seen.has(screen.path)) {
+            logger.critical(ErrorCode.STUDIO_SCREEN_PATH_DUPLICATE, `pikkuStudio declares two screens at '${screen.path}'; each screen needs its own path`);
+        }
+        seen.add(screen.path);
+    }
+    logger.debug(`• Found pikkuStudio: ${title} (${screens.length} screens)`);
+    state.studio = {
+        title,
+        file: node.getSourceFile().fileName,
+        screens,
+    };
+}
+/** The directory of the nearest package.json above the file: the addon package root. */
+const packageRoot = (file) => {
+    let dir = dirname(file);
+    while (true) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+};
+const readCatalog = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The checks on `pikkuStudio` that need the whole package: every title is a
+ * key in the addon's `messages/en.json` (a key missing from another locale is
+ * a warning), and every nav badge names one of the addon's functions.
+ */
+export function validatePikkuStudio(logger, state) {
+    const studio = state.studio;
+    if (!studio)
+        return;
+    const keys = [studio.title, ...studio.screens.map((screen) => screen.title)];
+    const root = packageRoot(studio.file);
+    const messagesDir = root ? join(root, 'messages') : undefined;
+    const en = messagesDir ? readCatalog(join(messagesDir, 'en.json')) : undefined;
+    for (const key of new Set(keys)) {
+        if (!en || !Object.hasOwn(en, key)) {
+            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `pikkuStudio uses the message key '${key}', which is missing from the addon's messages/en.json`);
+        }
+    }
+    if (messagesDir && existsSync(messagesDir)) {
+        const locales = readdirSync(messagesDir)
+            .filter((name) => name.endsWith('.json') && name !== 'en.json')
+            .sort();
+        for (const name of locales) {
+            const catalog = readCatalog(join(messagesDir, name)) ?? {};
+            for (const key of new Set(keys)) {
+                if (!Object.hasOwn(catalog, key)) {
+                    logger.warn(`pikkuStudio uses the message key '${key}', which is missing from the addon's messages/${name}`);
+                }
+            }
+        }
+    }
+    for (const screen of studio.screens) {
+        const badge = screen.nav?.badge;
+        if (badge !== undefined && !state.functions.meta[badge]) {
+            logger.critical(ErrorCode.STUDIO_BADGE_FUNCTION_NOT_FOUND, `Screen '${screen.path}' has the nav badge '${badge}', which names no function in this addon`);
+        }
+    }
+}

package/dist/add/add-rpc-invocations.js

@@ -164,6 +164,18 @@ export function addRPCInvocations(node, state, logger) {
                 state.workflows.invokedWorkflows.add(workflowName);
             }
         }
+        // rpc.startWorkflow('...'), workflowService.startWorkflow('...') and
+        // workflowService.runToCompletion('...') start a workflow by name
+        if (ts.isPropertyAccessExpression(expression) &&
+            (expression.name.text === 'startWorkflow' ||
+                expression.name.text === 'runToCompletion')) {
+            const [firstArg] = args;
+            if (firstArg &&
+                (ts.isStringLiteral(firstArg) ||
+                    ts.isNoSubstitutionTemplateLiteral(firstArg))) {
+                state.workflows.invokedWorkflows.add(firstArg.text);
+            }
+        }
         const agentCall = agentInvocationName(expression);
         if (agentCall) {
             const [firstArg] = args;

package/dist/add/check-disabled-references.d.ts

@@ -0,0 +1,27 @@
+import * as ts from 'typescript';
+import type { AddWiring, DisabledFunctionMeta, InspectorLogger, InspectorState } from '../types.js';
+/**
+ * A function's `disabled`, read from its config: `true`, or a non-empty string
+ * saying why. Anything else the build cannot read statically is refused rather
+ * than taken as enabled.
+ */
+export declare const readFunctionDisabled: (obj: ts.ObjectLiteralExpression, name: string, logger: InspectorLogger) => {
+    reason?: string;
+} | null;
+/**
+ * Records a function declared with `disabled`, in place of everything
+ * addFunctions would otherwise record. A function defined inline in what
+ * uses it is referenced by that, so it is refused instead.
+ */
+export declare const recordDisabledFunction: (logger: InspectorLogger, state: InspectorState, node: ts.CallExpression, pikkuFuncId: string, meta: DisabledFunctionMeta) => void;
+/**
+ * PKU562: anything that still references a disabled function — a wiring, an
+ * agent's tools, an `rpc.invoke` by name, any other code. Runs in the routes
+ * sweep, after every function is registered, so it sees the whole set.
+ */
+export declare const checkDisabledReferences: AddWiring;
+/**
+ * PKU562 for workflow steps, which name the function they call as a string
+ * the workflow meta already holds. Runs once, after the routes sweep.
+ */
+export declare const checkDisabledWorkflowSteps: (logger: InspectorLogger, state: InspectorState) => void;