@pikku/inspector 0.12.75 → 0.12.82

package/dist/add/add-feature-flag.js

@@ -0,0 +1,162 @@
+import * as ts from 'typescript';
+import { getPropertyValue } from '../utils/get-property-value.js';
+import { ErrorCode } from '../error-codes.js';
+const SEPARATOR = ':';
+const DEFINE_FEATURE_FLAGS = 'defineFeatureFlags';
+/**
+ * A call is the pikku one when the symbol it resolves to is, whatever the file
+ * chose to call it locally — `import { defineFeatureFlags as declare }` is an
+ * ordinary thing to write, and matching on the callee's text alone both misses
+ * that and claims a same-named local helper.
+ */
+const callsDefineFeatureFlags = (expression, checker) => {
+    if (!ts.isIdentifier(expression))
+        return false;
+    const symbol = checker.getSymbolAtLocation(expression);
+    if (!symbol)
+        return expression.text === DEFINE_FEATURE_FLAGS;
+    // An import specifier names what it imported even when the module itself does
+    // not resolve, which is every project whose deps are not installed yet.
+    const declaration = symbol.declarations?.[0];
+    if (declaration && ts.isImportSpecifier(declaration)) {
+        return ((declaration.propertyName ?? declaration.name).text ===
+            DEFINE_FEATURE_FLAGS);
+    }
+    // Only an imported symbol can be pikku's. A local const of the same name is
+    // a helper the file wrote for itself, and resolving it by name alone would
+    // claim it.
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+        return false;
+    const resolved = checker.getAliasedSymbol(symbol) ?? symbol;
+    return resolved.name === DEFINE_FEATURE_FLAGS;
+};
+/**
+ * The object literal a declaration's value is written as, following one level
+ * of indirection.
+ *
+ * `{ newCheckout }` and `{ newCheckout: flag }` both read naturally with the
+ * body declared above, and the flag's `anyOf` is extracted by AST — so the
+ * literal has to be found where it was written rather than the property being
+ * skipped, which would declare the flag with no capability constraint at all.
+ */
+const resolveObjectLiteral = (property, checker) => {
+    if (ts.isShorthandPropertyAssignment(property)) {
+        // The name of a shorthand resolves to the property, not to the value it
+        // stands for, which is what `getShorthandAssignmentValueSymbol` is for.
+        return fromSymbol(checker.getShorthandAssignmentValueSymbol(property), checker);
+    }
+    const unwrapped = unwrapAs(property.initializer);
+    if (ts.isObjectLiteralExpression(unwrapped))
+        return unwrapped;
+    if (!ts.isIdentifier(unwrapped))
+        return undefined;
+    return fromSymbol(checker.getSymbolAtLocation(unwrapped), checker);
+};
+const fromSymbol = (symbol, checker) => {
+    const resolved = symbol && symbol.flags & ts.SymbolFlags.Alias
+        ? (checker.getAliasedSymbol(symbol) ?? symbol)
+        : symbol;
+    for (const declaration of resolved?.declarations ?? []) {
+        if (!ts.isVariableDeclaration(declaration) || !declaration.initializer) {
+            continue;
+        }
+        const initializer = unwrapAs(declaration.initializer);
+        if (ts.isObjectLiteralExpression(initializer))
+            return initializer;
+    }
+    return undefined;
+};
+const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;
+/**
+ * Reads an optional `anyOf: [...]` array of string literals.
+ *
+ * Absent is not the same as empty: absent means no capability constraint, which
+ * is the shape of a pure kill switch, while an empty array satisfies nobody and
+ * is rejected downstream as a declaration mistake.
+ */
+const extractAnyOf = (obj, flagName, logger) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === 'anyOf');
+    if (!prop) {
+        return undefined;
+    }
+    if (!ts.isPropertyAssignment(prop) ||
+        !ts.isArrayLiteralExpression(prop.initializer)) {
+        logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${flagName}' must declare 'anyOf' as an array literal.`);
+        return undefined;
+    }
+    const scopes = [];
+    for (const element of prop.initializer.elements) {
+        const unwrapped = unwrapAs(element);
+        if (!ts.isStringLiteral(unwrapped)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${flagName}' lists a scope that is not a string literal. ` +
+                `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`);
+            continue;
+        }
+        scopes.push(unwrapped.text);
+    }
+    return scopes;
+};
+export const addFeatureFlag = (logger, node, checker, state, _options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    if (!callsDefineFeatureFlags(node.expression, checker)) {
+        return;
+    }
+    const firstArg = node.arguments[0];
+    if (!firstArg) {
+        return;
+    }
+    const unwrapped = unwrapAs(firstArg);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    for (const prop of unwrapped.properties) {
+        const shorthand = ts.isShorthandPropertyAssignment(prop);
+        if (!shorthand && !ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        let name;
+        if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+            name = prop.name.text;
+        }
+        if (name === undefined) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A feature flag is declared with a key that is not a literal.');
+            continue;
+        }
+        if (name.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, 'A feature flag is declared with an empty name.');
+            continue;
+        }
+        if (name.includes(SEPARATOR)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' contains the '${SEPARATOR}' separator. ` +
+                `'${SEPARATOR}' delimits scope ids; a flag named like a scope reads as one.`);
+            continue;
+        }
+        const body = resolveObjectLiteral(prop, checker);
+        if (!body) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' must be an object literal, or a variable holding one. ` +
+                `'anyOf' is extracted by AST, so a value this file cannot see would declare the flag with no capability constraint.`);
+            continue;
+        }
+        const anyOf = extractAnyOf(body, name, logger);
+        if (anyOf !== undefined && anyOf.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, `Feature flag '${name}' declares 'anyOf: []'. An empty list satisfies ` +
+                `nobody: omit 'anyOf' for a pure switch, or name the scopes that reveal it.`);
+            continue;
+        }
+        const description = getPropertyValue(body, 'description');
+        state.featureFlags.files.add(sourceFile);
+        state.featureFlags.definitions.push({
+            name,
+            description: description || undefined,
+            anyOf,
+            sourceFile,
+        });
+    }
+};

package/dist/add/add-middleware.js

@@ -47,6 +47,52 @@ function recordMiddlewareGroup(groups, key, group) {
         services: Array.from(new Set([...existing.services.services, ...group.services.services])),
     };
 }
+/**
+ * Record one `add*Middleware` call's entries in the instance map, giving each
+ * entry an id that is unique across the whole inspection.
+ *
+ * The index used to restart at 0 for every call, so a second file registering
+ * against the same group (or against `global`, which is one group for the whole
+ * project) minted ids the first file already owned and silently overwrote its
+ * entries. For `global:*` that is fatal rather than cosmetic: the instance map
+ * is the only record of a global registration, and per-unit deploy codegen
+ * emits its side-effect imports from that map — a lost entry means the module
+ * is never imported, `addGlobalMiddleware` never runs, and an auth gate is
+ * simply absent from the deployed unit with nothing in the build log.
+ *
+ * Allocating from the ids already present makes N registrations against one
+ * group produce N distinct entries, whatever order the files are visited in.
+ */
+function registerMiddlewareInstances(instances, groupType, groupKey, entries, sourceFile, position) {
+    // The inspector may revisit a file; the same call site is not a second
+    // registration, and re-allocating would inflate the map on every pass.
+    const alreadyRecorded = Object.entries(instances)
+        .filter(([id, instance]) => instance.sourceFile === sourceFile &&
+        instance.position === position &&
+        id.startsWith(`${makeContextBasedId(groupType, groupKey)}:`))
+        .map(([id]) => id);
+    if (alreadyRecorded.length === entries.length) {
+        return alreadyRecorded;
+    }
+    const instanceIds = [];
+    let next = 0;
+    for (const entry of entries) {
+        let instanceId = makeContextBasedId(groupType, groupKey, String(next));
+        while (instances[instanceId]) {
+            next++;
+            instanceId = makeContextBasedId(groupType, groupKey, String(next));
+        }
+        instances[instanceId] = {
+            definitionId: entry.definitionId,
+            sourceFile,
+            position,
+            isFactoryCall: entry.isFactoryCall,
+        };
+        instanceIds.push(instanceId);
+        next++;
+    }
+    return instanceIds;
+}
 function renameTempDefinitions(state, definitionIds, groupType, groupKey, storeKey = 'middleware') {
     const tempIndices = definitionIds
         .map((name, i) => (name.startsWith('__temp_') ? i : -1))
@@ -237,17 +283,10 @@ export const addMiddleware = (logger, node, checker, state) => {
             renameTempDefinitions(state, definitionIds, 'tag', tag);
         }
         const sourceFile = node.getSourceFile().fileName;
-        const instanceIds = [];
-        for (let i = 0; i < refs.length; i++) {
-            const instanceId = makeContextBasedId('tag', tag, String(i));
-            state.middleware.instances[instanceId] = {
-                definitionId: definitionIds[i],
-                sourceFile,
-                position: node.getStart(),
-                isFactoryCall: refs[i].isFactoryCall,
-            };
-            instanceIds.push(instanceId);
-        }
+        const instanceIds = registerMiddlewareInstances(state.middleware.instances, 'tag', tag, refs.map((ref, i) => ({
+            definitionId: definitionIds[i],
+            isFactoryCall: ref.isFactoryCall,
+        })), sourceFile, node.getStart());
         const allServices = new Set();
         for (const defId of definitionIds) {
             const def = state.middleware.definitions[defId];
@@ -309,15 +348,14 @@ export const addMiddleware = (logger, node, checker, state) => {
             renameTempDefinitions(state, definitionIds, 'global', 'middleware');
         }
         const sourceFile = node.getSourceFile().fileName;
-        for (let i = 0; i < refs.length; i++) {
-            const instanceId = makeContextBasedId('global', 'middleware', String(i));
-            state.middleware.instances[instanceId] = {
-                definitionId: definitionIds[i],
-                sourceFile,
-                position: node.getStart(),
-                isFactoryCall: refs[i].isFactoryCall,
-            };
-        }
+        registerMiddlewareInstances(state.middleware.instances, 'global', 'middleware', refs.map((ref, i) => ({
+            definitionId: definitionIds[i],
+            isFactoryCall: ref.isFactoryCall,
+        })), sourceFile, node.getStart());
+        // The instance map is one map for the whole project, and codegen reads it
+        // by string-prefix. This set is the independent witness that lets codegen
+        // fail loudly if a global registration ever goes missing from it.
+        state.middleware.globalFiles.add(sourceFile);
         // Without this, bootstrap codegen's "import every file with a wire-call"
         // pass skips middleware-only files and the registration never runs.
         state.http.files.add(sourceFile);
@@ -347,17 +385,10 @@ export const addMiddleware = (logger, node, checker, state) => {
             renameTempDefinitions(state, definitionIds, 'http', pattern);
         }
         const sourceFile = node.getSourceFile().fileName;
-        const instanceIds = [];
-        for (let i = 0; i < refs.length; i++) {
-            const instanceId = makeContextBasedId('http', pattern, String(i));
-            state.middleware.instances[instanceId] = {
-                definitionId: definitionIds[i],
-                sourceFile,
-                position: node.getStart(),
-                isFactoryCall: refs[i].isFactoryCall,
-            };
-            instanceIds.push(instanceId);
-        }
+        const instanceIds = registerMiddlewareInstances(state.middleware.instances, 'http', pattern, refs.map((ref, i) => ({
+            definitionId: definitionIds[i],
+            isFactoryCall: ref.isFactoryCall,
+        })), sourceFile, node.getStart());
         const allServices = new Set();
         for (const defId of definitionIds) {
             const def = state.middleware.definitions[defId];
@@ -581,17 +612,10 @@ export const addMiddleware = (logger, node, checker, state) => {
         const definitionIds = refs.map((r) => r.definitionId);
         renameTempDefinitions(state, definitionIds, 'tag', tag, 'channelMiddleware');
         const sourceFile = node.getSourceFile().fileName;
-        const instanceIds = [];
-        for (let i = 0; i < refs.length; i++) {
-            const instanceId = makeContextBasedId('tag', tag, String(i));
-            state.channelMiddleware.instances[instanceId] = {
-                definitionId: definitionIds[i],
-                sourceFile,
-                position: node.getStart(),
-                isFactoryCall: refs[i].isFactoryCall,
-            };
-            instanceIds.push(instanceId);
-        }
+        const instanceIds = registerMiddlewareInstances(state.channelMiddleware.instances, 'tag', tag, refs.map((ref, i) => ({
+            definitionId: definitionIds[i],
+            isFactoryCall: ref.isFactoryCall,
+        })), sourceFile, node.getStart());
         const allServices = new Set();
         for (const defId of definitionIds) {
             const def = state.channelMiddleware.definitions[defId];

package/dist/add/add-wire-addon.js

@@ -70,10 +70,12 @@ export function addWireAddon(node, state, logger) {
         else if (key === 'rpcEndpoint' && ts.isStringLiteral(prop.initializer)) {
             rpcEndpoint = prop.initializer.text;
         }
-        else if (key === 'mcp' &&
-            (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
-                prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
-            mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        else if (key === 'mcp') {
+            mcp =
+                prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                    prop.initializer.kind === ts.SyntaxKind.FalseKeyword
+                    ? prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+                    : parseStringArray(prop.initializer);
         }
         else if (key === 'auth' &&
             (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
@@ -122,6 +124,7 @@ export function addWireAddon(node, state, logger) {
     logger.debug(`• Found wireAddon: ${name} → ${pkg}`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        file: node.getSourceFile().fileName,
         rpcEndpoint,
         mcp,
         auth,

package/dist/add/add-wire-remote-addon.js

@@ -57,6 +57,7 @@ export function addWireRemoteAddon(node, state, logger) {
     logger.debug(`• Found wireRemoteAddon: ${name} → ${pkg} (remote)`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        file: node.getSourceFile().fileName,
         remote: true,
         hasAuth,
         authCredentialId,

package/dist/error-codes.d.ts

@@ -32,6 +32,7 @@ export declare enum ErrorCode {
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     ADDON_NOT_INSTALLED = "PKU340",
+    ADDON_MCP_FUNCTION_NOT_FOUND = "PKU341",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -35,6 +35,7 @@ export var ErrorCode;
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
     ErrorCode["ADDON_NOT_INSTALLED"] = "PKU340";
+    ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { ScenarioInstrumentationFunction } from './add/scenario-instrumenta
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
-export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
+export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
 export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
@@ -24,3 +24,5 @@ export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export type { SerializedWorkflowGraph, SerializedWorkflowGraphs, } from './utils/workflow/graph/index.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
+export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
 export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
-export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
+export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
@@ -13,3 +13,5 @@ export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWork
 export { getFilesAndMethods } from './utils/get-files-and-methods.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
+export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
+export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';

package/dist/inspector.js

@@ -160,6 +160,10 @@ export function getInitialInspectorState(rootDir) {
             definitions: [],
             files: new Set(),
         },
+        featureFlags: {
+            definitions: [],
+            files: new Set(),
+        },
         personas: {
             definitions: [],
             files: new Set(),
@@ -177,6 +181,7 @@ export function getInitialInspectorState(rootDir) {
             definitions: {},
             instances: {},
             tagMiddleware: new Map(),
+            globalFiles: new Set(),
         },
         channelMiddleware: {
             definitions: {},

package/dist/surface/collect-surface.d.ts

@@ -0,0 +1,58 @@
+export type SurfaceKind = 'function' | 'class' | 'interface' | 'type' | 'const' | 'enum' | 'namespace';
+export type SurfaceSymbol = {
+    name: string;
+    kind: SurfaceKind;
+    declaredAt: string;
+    /** Absolute path of the declaring file, or null when it could not be found. */
+    declaredIn: string | null;
+    deprecated: boolean;
+    /** The text of the `@deprecated` tag, when it carries one. */
+    deprecatedReason?: string;
+    /** First paragraph of the symbol's JSDoc. */
+    summary?: string;
+    /** The symbol's JSDoc in full, paragraphs and examples included. */
+    docs?: string;
+    /** The type as the checker prints it, so a caller knows how to call it. */
+    signature?: string;
+    /**
+     * The shape written at the call site, one `name?: type` per entry — the
+     * properties of the object a function takes, or of the type itself. The
+     * signature names that shape; this says what is in it.
+     */
+    members?: SurfaceMember[];
+    /** The `@example` blocks, which the documentation comment leaves out. */
+    examples?: string[];
+    /** The HTTP status an error class is registered with. */
+    status?: number;
+};
+export type SurfaceEntrypoint = {
+    subpath: string;
+    specifier: string;
+    entryFile: string;
+    symbols: SurfaceSymbol[];
+};
+export type CollectSurfaceOptions = {
+    /**
+     * Read the package's `imports` map instead of its `exports` map, taking the
+     * one key given — `#pikku/*` is what an application reaches its generated
+     * leaves through, and it is a private specifier rather than a published one.
+     */
+    importsSubpath?: string;
+    /** Restrict collection to these subpaths, so the program stays small. */
+    subpaths?: string[];
+    /** The snippet regions an `@example snippet: name` resolves against. */
+    snippets?: Map<string, string>;
+};
+export declare class UnknownSnippetError extends Error {
+    constructor(name: string, symbol: string, known: string[]);
+}
+/**
+ * One key of an options object: how it is written, and — where the declaring
+ * type says so — what it means. `schedule: string` is a shape; "a cron
+ * expression" is what a caller actually needs, and only the JSDoc has it.
+ */
+export type SurfaceMember = {
+    line: string;
+    doc?: string;
+};
+export declare const collectSurface: (packageDir: string, { importsSubpath, subpaths, snippets }?: CollectSurfaceOptions) => Promise<SurfaceEntrypoint[]>;