@pikku/inspector 0.12.103 → 0.12.107

package/dist/utils/canonical-type-string.js

@@ -0,0 +1,162 @@
+/**
+ * A printed type with the members of every union in it sorted: by text, with
+ * `null` and `undefined` last. The checker prints a union in the order its
+ * members were created, which follows whichever file it happened to check
+ * first, and so differs between runtimes and between the TypeScript and native
+ * inspectors. Everything other than a union's order is left byte for byte.
+ *
+ * A level the scanner cannot split safely (a conditional type, a type
+ * parameter's constraint, a type predicate) keeps its order and only has the
+ * brackets inside it canonicalized. The native inspector's
+ * `typesmap.CanonicalTypeString` is the same algorithm, and both run the cases
+ * in `canonical-type-string.cases.json`.
+ */
+export const canonicalTypeString = (type) => {
+    const lead = type.length - type.replace(/^[ \t\n\r]+/, '').length;
+    const trail = type.length - type.replace(/[ \t\n\r]+$/, '').length;
+    if (lead === type.length)
+        return type;
+    const body = type.slice(lead, type.length - trail);
+    return (type.slice(0, lead) + canonicalBody(body) + type.slice(type.length - trail));
+};
+const OPENERS = '{[(<';
+const CLOSE = { '{': '}', '[': ']', '(': ')', '<': '>' };
+const CLOSERS = '}])>';
+const QUOTES = `"'\``;
+const UNSPLITTABLE = new Set(['extends', 'is', 'asserts', 'infer', 'as']);
+const MAPPED_KEY = /^[A-Za-z_$][\w$]*[ \t\n\r]+in[ \t\n\r]/;
+/** Where the comment starting at `i` ends (exclusive), or -1 if none starts there. */
+const commentEnd = (s, i) => {
+    if (s[i] !== '/')
+        return -1;
+    if (s[i + 1] === '*') {
+        const end = s.indexOf('*/', i + 2);
+        return end === -1 ? s.length : end + 2;
+    }
+    if (s[i + 1] === '/') {
+        const end = s.indexOf('\n', i + 2);
+        return end === -1 ? s.length : end;
+    }
+    return -1;
+};
+/**
+ * `s` with everything inside brackets, string literals and comments blanked,
+ * and the outermost bracket pairs.
+ */
+const topLevel = (s) => {
+    const mask = Array.from({ length: s.length }, () => ' ');
+    const groups = [];
+    let depth = 0;
+    let open = -1;
+    for (let i = 0; i < s.length; i++) {
+        const char = s[i];
+        if (QUOTES.includes(char)) {
+            let j = i + 1;
+            while (j < s.length && s[j] !== char)
+                j += s[j] === '\\' ? 2 : 1;
+            i = j;
+            continue;
+        }
+        const end = commentEnd(s, i);
+        if (end !== -1) {
+            i = end - 1;
+            continue;
+        }
+        if (OPENERS.includes(char)) {
+            if (depth === 0)
+                open = i;
+            depth++;
+        }
+        else if (CLOSERS.includes(char) && !(char === '>' && s[i - 1] === '=')) {
+            if (depth > 0)
+                depth--;
+            if (depth === 0 && open !== -1 && CLOSE[s[open]] === char) {
+                groups.push([open, i]);
+                open = -1;
+            }
+        }
+        else if (depth === 0) {
+            mask[i] = char;
+        }
+    }
+    return { mask: mask.join(''), groups };
+};
+const isNullish = (member) => member === 'null' || member === 'undefined';
+const sortMembers = (members) => members.sort((a, b) => isNullish(a) !== isNullish(b)
+    ? isNullish(a)
+        ? 1
+        : -1
+    : a < b
+        ? -1
+        : a > b
+            ? 1
+            : 0);
+const unsplittable = (mask) => {
+    if (/[?:]/.test(mask))
+        return true;
+    for (let i = 0; i < mask.length; i++) {
+        if (mask[i] === '=' && mask[i + 1] !== '>')
+            return true;
+    }
+    return mask.split(/[^A-Za-z0-9_$]+/).some((word) => UNSPLITTABLE.has(word));
+};
+const canonicalBody = (body) => {
+    const { mask } = topLevel(body);
+    const arrow = mask.indexOf('=>');
+    if (arrow !== -1 && !mask.slice(0, arrow).includes('|')) {
+        return `${rewriteGroups(body.slice(0, arrow))}=>${canonicalTypeString(body.slice(arrow + 2))}`;
+    }
+    const mapped = MAPPED_KEY.exec(mask);
+    if (mapped) {
+        const key = mapped[0].length;
+        return body.slice(0, key) + canonicalTypeString(body.slice(key));
+    }
+    if (!mask.includes('|') || unsplittable(mask))
+        return rewriteGroups(body);
+    const members = [];
+    let start = 0;
+    for (let i = 0; i <= mask.length; i++) {
+        if (i === mask.length || mask[i] === '|') {
+            const member = canonicalTypeString(body.slice(start, i)).trim();
+            if (member)
+                members.push(member);
+            start = i + 1;
+        }
+    }
+    return members.length > 1
+        ? sortMembers(members).join(' | ')
+        : rewriteGroups(body);
+};
+/** `s` with the contents of each outermost bracket pair canonicalized. */
+const rewriteGroups = (s) => {
+    let out = '';
+    let last = 0;
+    for (const [open, close] of topLevel(s).groups) {
+        out +=
+            s.slice(last, open + 1) + rewriteList(s.slice(open + 1, close), s[open]);
+        last = close;
+    }
+    return out + s.slice(last);
+};
+/** A bracket's contents: members of an object, parameters, or type arguments. */
+const rewriteList = (inner, opener) => {
+    const separators = opener === '{' ? ';,' : ',';
+    const { mask } = topLevel(inner);
+    let out = '';
+    let start = 0;
+    for (let i = 0; i <= mask.length; i++) {
+        if (i === mask.length || separators.includes(mask[i])) {
+            out += rewriteItem(inner.slice(start, i), opener) + (inner[i] ?? '');
+            start = i + 1;
+        }
+    }
+    return out;
+};
+const rewriteItem = (item, opener) => {
+    if (opener === '<')
+        return canonicalTypeString(item);
+    const colon = topLevel(item).mask.indexOf(':');
+    if (colon === -1)
+        return canonicalTypeString(item);
+    return `${rewriteGroups(item.slice(0, colon))}:${canonicalTypeString(item.slice(colon + 1))}`;
+};

package/dist/utils/context-based-id.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The id of a function wired inline rather than declared on its own: the
+ * wiring type followed by whatever identifies the wiring (`queue:emails`,
+ * `http:get:/todos`). Kept apart from `extract-function-name.ts`, which needs
+ * the TypeScript compiler, so pure state helpers can use it without loading it.
+ */
+export declare function makeContextBasedId(wiringType: string, ...segments: string[]): string;

package/dist/utils/context-based-id.js

@@ -0,0 +1,9 @@
+/**
+ * The id of a function wired inline rather than declared on its own: the
+ * wiring type followed by whatever identifies the wiring (`queue:emails`,
+ * `http:get:/todos`). Kept apart from `extract-function-name.ts`, which needs
+ * the TypeScript compiler, so pure state helpers can use it without loading it.
+ */
+export function makeContextBasedId(wiringType, ...segments) {
+    return [wiringType, ...segments].join(':');
+}

package/dist/utils/custom-types-generator.d.ts

@@ -6,4 +6,18 @@ import type { TypesMap } from '../types-map.js';
  * ts-json-schema-generator can discover inline/custom types from typesMap.
  */
 export declare function sanitizeTypeName(name: string): string;
-export declare function generateCustomTypes(typesMap: TypesMap, requiredTypes: Set<string>): string;
+/**
+ * The names `generateCustomTypes` declares, in the order it declares them. A
+ * file that imports from the shared custom-types file uses this to know which
+ * names exist there.
+ */
+export declare function customTypeNames(typesMap: TypesMap): string[];
+export interface GenerateCustomTypesOptions {
+    /**
+     * Turns the absolute path of a type's source file into the specifier the
+     * import line uses. Left out, the absolute path is used as-is — fine for the
+     * in-memory source the schema generator compiles, wrong for a file on disk.
+     */
+    resolveImportPath?: (absolutePath: string) => string;
+}
+export declare function generateCustomTypes(typesMap: TypesMap, requiredTypes: Set<string>, { resolveImportPath }?: GenerateCustomTypesOptions): string;

package/dist/utils/custom-types-generator.js

@@ -55,14 +55,26 @@ function stripClassificationWrappers(type) {
     }
     return output;
 }
-export function generateCustomTypes(typesMap, requiredTypes) {
-    const typeDeclarations = Array.from(typesMap.customTypes.entries())
+function emittableCustomTypes(typesMap) {
+    return Array.from(typesMap.customTypes.entries())
         .sort(([a], [b]) => a.localeCompare(b))
         .filter(([_name, { type }]) => {
         const hasUndefinedGeneric = /\b(Name|In|Out|Key)\b/.test(type) && /\[.*\]/.test(type);
         return !hasUndefinedGeneric;
-    })
-        .map(([originalName, { type, references }]) => {
+    });
+}
+/**
+ * The names `generateCustomTypes` declares, in the order it declares them. A
+ * file that imports from the shared custom-types file uses this to know which
+ * names exist there.
+ */
+export function customTypeNames(typesMap) {
+    return emittableCustomTypes(typesMap)
+        .filter(([originalName, { type }]) => sanitizeTypeName(originalName) !== stripClassificationWrappers(type))
+        .map(([originalName]) => sanitizeTypeName(originalName));
+}
+export function generateCustomTypes(typesMap, requiredTypes, { resolveImportPath = (path) => path } = {}) {
+    const typeDeclarations = emittableCustomTypes(typesMap).map(([originalName, { type, references }]) => {
         const name = sanitizeTypeName(originalName);
         references.forEach((refName) => {
             if (refName !== '__object' &&
@@ -118,7 +130,7 @@ export function generateCustomTypes(typesMap, requiredTypes) {
         }
     }
     const importLines = Array.from(importsByPath.entries())
-        .map(([path, types]) => `import type { ${Array.from(types).join(', ')} } from '${path}'`)
+        .map(([path, types]) => `import type { ${Array.from(types).join(', ')} } from '${resolveImportPath(path)}'`)
         .join('\n');
     return `${importLines}\n\n${typeDeclarations.filter(Boolean).join('\n')}`;
 }

package/dist/utils/ensure-function-metadata.d.ts

@@ -7,18 +7,4 @@ import type { InspectorState } from '../types.js';
  * extracts tags/middleware/permissions from the pikkuFunc() config.
  */
 export declare function ensureFunctionMetadata(state: InspectorState, pikkuFuncId: string, fallbackName?: string, funcInitializer?: ts.Node, checker?: ts.TypeChecker, isHelper?: boolean): void;
-/**
- * Register metadata for a `func:` inlined into a wiring (queue/scheduler/
- * trigger/gateway/…).
- *
- * An inline function has no exported name, so `addFunctions` skips it (it bails
- * on `__temp_` ids) and only the wiring's context-based id exists. Without this
- * the wiring points at a function that was never registered and the worker
- * resolves to nothing at runtime ("Missing generated metadata for ...").
- *
- * The stub also carries no session info, so the runtime would treat it as
- * session-required and every invocation would fail with "Authentication
- * required". Derive `sessionless` from the helper the function was built with —
- * the same rule `addFunctions` applies to named ones (`!== 'pikkuFunc'`).
- */
 export declare function ensureInlineWiringFunction(state: InspectorState, pikkuFuncId: string, fallbackName: string | undefined, funcInitializer: ts.Node, checker: ts.TypeChecker, isHelper?: boolean): void;

package/dist/utils/ensure-function-metadata.js

@@ -3,6 +3,7 @@ import { funcIdToTypeName } from './extract-function-name.js';
 import { getCommonWireMetaData } from './get-property-value.js';
 import { resolveMiddleware } from './middleware.js';
 import { resolvePermissions } from './permissions.js';
+import { resolveCalleeName } from './resolve-callee-name.js';
 function isVoidLike(type) {
     return !!(type.flags &
         (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.VoidLike));
@@ -224,6 +225,7 @@ export function ensureFunctionMetadata(state, pikkuFuncId, fallbackName, funcIni
  * required". Derive `sessionless` from the helper the function was built with —
  * the same rule `addFunctions` applies to named ones (`!== 'pikkuFunc'`).
  */
+const isPikkuFunc = (name) => name === 'pikkuFunc';
 export function ensureInlineWiringFunction(state, pikkuFuncId, fallbackName, funcInitializer, checker, isHelper) {
     ensureFunctionMetadata(state, pikkuFuncId, fallbackName, funcInitializer, checker, isHelper);
     const meta = state.functions.meta[pikkuFuncId];
@@ -231,7 +233,8 @@ export function ensureInlineWiringFunction(state, pikkuFuncId, fallbackName, fun
         meta.sessionless === undefined &&
         ts.isCallExpression(funcInitializer) &&
         ts.isIdentifier(funcInitializer.expression)) {
-        meta.sessionless = funcInitializer.expression.text !== 'pikkuFunc';
+        meta.sessionless =
+            resolveCalleeName(funcInitializer, checker, isPikkuFunc) !== 'pikkuFunc';
     }
 }
 function populateTypesLookup(state, pikkuFuncId, funcInitializer, checker) {

package/dist/utils/extract-function-name.d.ts

@@ -8,7 +8,7 @@ export type ExtractedFunctionName = {
     isHelper: boolean;
     version: number | null;
 };
-export declare function makeContextBasedId(wiringType: string, ...segments: string[]): string;
+export { makeContextBasedId } from './context-based-id.js';
 export declare function funcIdToTypeName(id: string): string;
 export declare function extractFunctionName(callExpr: ts.Node, checker: ts.TypeChecker, rootDir: string): ExtractedFunctionName;
 /**

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

@@ -18,9 +18,7 @@ function tempFuncId(callExpr, rootDir) {
         .slice(0, 16);
     return `__temp_${hash}`;
 }
-export function makeContextBasedId(wiringType, ...segments) {
-    return [wiringType, ...segments].join(':');
-}
+export { makeContextBasedId } from './context-based-id.js';
 export function funcIdToTypeName(id) {
     return id
         .split(/[^a-zA-Z0-9]/)
@@ -30,7 +28,7 @@ export function funcIdToTypeName(id) {
 }
 /**
  * The step wrappers, whichever kind of subject acts in them. A scenario calls a
- * platform or addon step by name exactly as it calls a persona one.
+ * platform or addon step by name exactly as it calls a virtual user one.
  */
 const SCENARIO_STEP_WRAPPERS = new Set([
     'pikkuScenarioStep',

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

@@ -1,5 +1,5 @@
 import { parseVersionedId } from '@pikku/core/utils';
-import { makeContextBasedId } from './extract-function-name.js';
+import { makeContextBasedId } from './context-based-id.js';
 import { aggregateRequiredServices } from './post-process.js';
 import { IncompatibleDeployTargetError, resolveDeployTarget, } from './resolve-deploy-target.js';
 /**
@@ -359,6 +359,11 @@ export function filterInspectorState(state, filters, logger) {
             meta: JSON.parse(JSON.stringify(state.channels.meta)),
             files: new Set(), // Will be repopulated with filtered files
         },
+        gateways: {
+            ...state.gateways,
+            meta: JSON.parse(JSON.stringify(state.gateways?.meta ?? {})),
+            files: new Set(),
+        },
         triggers: {
             ...state.triggers,
             meta: JSON.parse(JSON.stringify(state.triggers?.meta ?? {})),
@@ -511,6 +516,31 @@ export function filterInspectorState(state, filters, logger) {
         }
     }
     filteredState.channels.files = repopulateFileSetFromMeta(filteredState.channels.meta, state.channels.files, Object.keys(filteredState.channels.meta).length > 0);
+    // Filter gateways. A gateway is addressed by its own name or by the function
+    // it runs, so a deploy unit naming either keeps the wiring that serves it.
+    for (const name of Object.keys(filteredState.gateways.meta)) {
+        const gatewayMeta = filteredState.gateways.meta[name];
+        const matches = matchesFilters(filters, {
+            type: 'gateway',
+            name: gatewayMeta.pikkuFuncId,
+            altNames: [name],
+            tags: gatewayMeta.tags,
+            httpRoute: gatewayMeta.route,
+        }, logger, undefined, keptByDeploy);
+        if (!matches) {
+            delete filteredState.gateways.meta[name];
+        }
+        else {
+            filteredState.serviceAggregation.usedFunctions.add(gatewayMeta.pikkuFuncId);
+            extractWireNames(gatewayMeta.middleware).forEach((name) => filteredState.serviceAggregation.usedMiddleware.add(name));
+        }
+    }
+    // The meta records no source file per gateway, so a surviving gateway keeps
+    // every gateway file and none surviving drops them all.
+    filteredState.gateways.files =
+        Object.keys(filteredState.gateways.meta).length > 0
+            ? new Set(state.gateways?.files ?? [])
+            : new Set();
     // Filter triggers
     for (const name of Object.keys(filteredState.triggers.meta)) {
         const triggerMeta = filteredState.triggers.meta[name];

package/dist/utils/get-property-value.d.ts

@@ -1,6 +1,11 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
 export declare const getArrayPropertyValue: (obj: ts.ObjectLiteralExpression, propertyName: string) => string[] | null;
+/**
+ * Returns the object literal assigned to a property, or null when the property
+ * is absent or is not an inline object.
+ */
+export declare const getObjectPropertyLiteral: (obj: ts.ObjectLiteralExpression, propertyName: string) => ts.ObjectLiteralExpression | null;
 /**
  * Extracts a string->string record from an object property.
  *

package/dist/utils/get-property-value.js

@@ -27,6 +27,20 @@ export const getArrayPropertyValue = (obj, propertyName) => {
     }
     return null;
 };
+/**
+ * Returns the object literal assigned to a property, or null when the property
+ * is absent or is not an inline object.
+ */
+export const getObjectPropertyLiteral = (obj, propertyName) => {
+    const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === propertyName);
+    if (!property || !ts.isPropertyAssignment(property)) {
+        return null;
+    }
+    const initializer = unwrapAs(property.initializer);
+    return ts.isObjectLiteralExpression(initializer) ? initializer : null;
+};
 /**
  * Extracts a string->string record from an object property.
  *
@@ -102,7 +116,7 @@ export const assertStringLiteralProperty = (obj, propertyName, wiringType, logge
  * that anything written as an expression comes through raw: a `description`
  * split across lines as `'Fetch the thing ' + 'from upstream'` reaches
  * `infra.json` with the quotes and the `+` still in it, and is rendered that
- * way in the fabric console.
+ * way in the cloud console.
  *
  * Deliberately checker-free, unlike `extractStringLiteral`. Every value this
  * resolves is a literal in the same expression, so no symbol resolution is

package/dist/utils/inspector-constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The pikku function id of the single shared auth handler the CLI generates
+ * (`export const authHandler = pikkuSessionlessFunc(...)` in auth.gen.ts). An
+ * exported top-level const collapses the catch-all `/api/auth/**` route onto one
+ * worker, and the export name becomes the function id. Shared with the CLI
+ * codegen and the post-process service stamp so all three agree on the same id
+ * without the inspector having to import `@pikku/better-auth`.
+ */
+export declare const AUTH_HANDLER_FUNC_ID = "authHandler";
+/**
+ * Placeholder recorded when a scenario step's target isn't a static string
+ * literal. The step is kept rather than dropped so post-processing can raise
+ * PKU678 against it — a dropped step is the silent-failure mode this repo has
+ * hit repeatedly on workflow graph round-trips.
+ */
+export declare const DYNAMIC_SCENARIO_STEP_TARGET = "<dynamic>";

package/dist/utils/inspector-constants.js

@@ -0,0 +1,16 @@
+/**
+ * The pikku function id of the single shared auth handler the CLI generates
+ * (`export const authHandler = pikkuSessionlessFunc(...)` in auth.gen.ts). An
+ * exported top-level const collapses the catch-all `/api/auth/**` route onto one
+ * worker, and the export name becomes the function id. Shared with the CLI
+ * codegen and the post-process service stamp so all three agree on the same id
+ * without the inspector having to import `@pikku/better-auth`.
+ */
+export const AUTH_HANDLER_FUNC_ID = 'authHandler';
+/**
+ * Placeholder recorded when a scenario step's target isn't a static string
+ * literal. The step is kept rather than dropped so post-processing can raise
+ * PKU678 against it — a dropped step is the silent-failure mode this repo has
+ * hit repeatedly on workflow graph round-trips.
+ */
+export const DYNAMIC_SCENARIO_STEP_TARGET = '<dynamic>';

package/dist/utils/load-addon-functions-meta.js

@@ -45,6 +45,7 @@ const applyPackageToCLICommands = (commands, packageName, namespace) => {
             }
             if (namespace &&
                 typeof command.pikkuFuncId === 'string' &&
+                command.pikkuFuncId !== '' &&
                 !command.pikkuFuncId.includes(':')) {
                 command.pikkuFuncId = `${namespace}:${command.pikkuFuncId}`;
             }