@pikku/inspector 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,4 +1,29 @@
-## 0.11.0
+## 0.12.0
+
+### New Features
+
+- AI agent metadata extraction
+- HTTP route groups analysis
+- Trigger and trigger source analysis
+- Secret and variable declaration extraction
+- Workflow graph inspection and DSL extraction
+- Contract hashing for change detection
+- OpenAPI spec generation (moved from CLI)
+
+## 0.11.2
+
+### Patch Changes
+
+- db9c7bf: Add workflow graph inspection and DSL extraction
+- Updated dependencies [db9c7bf]
+  - @pikku/core@0.11.2
+
+### Features
+
+- f35e89da: Add workflow graph inspection and DSL extraction
+  - Workflow graph inspection with `add-workflow-graph.ts`
+  - DSL workflow extraction utilities (extract, deserialize, validate)
+  - DSL to graph conversion for metadata generation
 
 ## 0.11.1
 

package/OPTIMIZATION-PLAN.md

@@ -0,0 +1,195 @@
+# Inspector Package Optimization Plan
+
+## Context
+
+The inspector (`packages/inspector/src/`) is a static code analyzer built on TypeScript's compiler API. It extracts metadata from source files via a two-pass AST visitor pattern (setup + routes). Profiling reveals that for **every AST node**, all handlers are called sequentially (10 in setup, 16 in routes) even though only 1 ever matches. This creates millions of wasted function calls on large codebases.
+
+The inspector already has `performance.now()` instrumentation for 7 phases. We'll use this to measure each optimization independently.
+
+---
+
+## Step 0: Create Benchmark Harness
+
+**Goal:** Establish reproducible baseline measurements.
+
+**File:** `src/benchmark.ts`
+
+**What it does:**
+
+- Collects `.ts` files from a target directory (e.g., the external repo's packages)
+- Runs `inspect()` N iterations (default 10) with a warmup run
+- Parses existing `logger.debug` messages to capture per-phase timings
+- Reports median, mean, min, max for each phase + total
+- Outputs JSON for before/after diffing
+- Also benchmarks `filterInspectorState()` separately using the test fixture (`src/utils/test-data/inspector-state.json`)
+- Adds counters for: total AST nodes visited, CallExpression nodes, dispatch hits
+
+**Run with:**
+
+```bash
+node --import tsx src/benchmark.ts <target-dir> <iterations>
+```
+
+**How to verify:** Run 3x, confirm <5% variance between runs for each phase.
+
+---
+
+## Step 1: Identifier-Based Dispatch Map in `visit.ts`
+
+**File:** `src/visit.ts`
+
+**Problem:** Every AST node goes through ALL handlers. In `visitRoutes`, that's 16 function calls per node. Each handler independently checks `isCallExpression` -> `isIdentifier` -> `expression.text === 'xyz'`. For non-CallExpression nodes (the vast majority), all 16 calls are wasted.
+
+**Fix:** Check node kind once, extract identifier once, use `Map<string, handler>` for O(1) dispatch.
+
+**Dispatch map for `visitRoutes`** (all handlers expect CallExpression + Identifier):
+
+| Identifier             | Handler               |
+| ---------------------- | --------------------- |
+| `wireHTTP`             | `addHTTPRoute`        |
+| `wireHTTPRoutes`       | `addHTTPRoutes`       |
+| `wireScheduler`        | `addSchedule`         |
+| `wireTrigger`          | `addTrigger`          |
+| `wireTriggerSource`    | `addTrigger`          |
+| `wireQueueWorker`      | `addQueueWorker`      |
+| `wireChannel`          | `addChannel`          |
+| `wireCLI`              | `addCLI`              |
+| `pikkuCLIRender`       | `addCLIRenderers`     |
+| `wireMCPResource`      | `addMCPResource`      |
+| `wireMCPTool`          | `addMCPTool`          |
+| `wireMCPPrompt`        | `addMCPPrompt`        |
+| `wireWorkflowGraph`    | `addWorkflowGraph`    |
+| `wireSecret`           | `addSecret`           |
+| `wireOAuth2Credential` | `addOAuth2Credential` |
+| `wireVariable`         | `addVariable`         |
+
+Fallback for unmatched identifiers: check `/pikku.*func/i` regex -> `addFunctions`.
+
+**Dispatch for `visitSetup`** (mixed node kinds):
+
+- `SyntaxKind.CallExpression` + Identifier -> map with: `external`, `workflow`, `workflowStart`, `workflowRun`, `workflowStatus`, `graphStart` -> `addRPCInvocations`; `pikkuMiddleware`, `pikkuMiddlewareFactory`, `addMiddleware`, `addHTTPMiddleware` -> `addMiddleware`; `pikkuPermission`, `pikkuPermissionFactory`, `addPermission`, `addHTTPPermission` -> `addPermission`; `pikkuWorkflowFunc`, `pikkuWorkflowComplexFunc` -> `addWorkflow`
+- `SyntaxKind.CallExpression` + PropertyAccessExpression (`rpc.invoke`) -> `addRPCInvocations`
+- `SyntaxKind.ClassDeclaration` / `InterfaceDeclaration` -> `addFileExtendsCoreType` (4 core type names)
+- `SyntaxKind.VariableDeclaration` -> `addFileWithFactory` (3 factory type names)
+- All other node kinds -> skip directly to recursion
+
+**Measure:** Compare "Visit setup phase" and "Visit routes phase" benchmark timings.
+
+**Expected improvement:** 30-60% reduction in visit phase times.
+
+**Verify:** `bash run-tests.sh` + compare serialized inspector state output before/after.
+
+---
+
+## Step 2: Hoist Regex + Remove Redundant Checks in `add-functions.ts`
+
+**File:** `src/add/add-functions.ts`
+
+**Problem (lines 290-309):**
+
+```ts
+// Line 301: regex re-created EVERY call (every AST node)
+const pikkuFuncPattern = /pikku.*func/i
+// Line 307: redundant - isIdentifier already checked at line 296,
+// startsWith('pikku') is a subset of the regex
+if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku'))
+```
+
+**Fix:**
+
+1. Move `const pikkuFuncPattern = /pikku.*func/i` to module scope
+2. Remove the redundant check at line 307-309
+
+**Measure:** "Visit routes phase" timing.
+
+**Expected improvement:** 1-5% of visit routes phase.
+
+**Verify:** `bash run-tests.sh`
+
+---
+
+## Step 3: Replace `getText()` with `.text` Property Access
+
+**Files:** 3-5 files, ~8 safe replacements
+
+`node.getText()` reconstructs text by slicing the source string. For `Identifier` nodes, `.text` is a direct property -- zero overhead.
+
+**Safe replacements:**
+
+- `src/add/add-file-extends-core-type.ts` line 13: `node.name?.getText()` -> `node.name?.text`
+- `src/add/add-file-with-factory.ts` line 24: `node.name.getText()` -> guard with `ts.isIdentifier(node.name) ? node.name.text : node.name.getText()`
+- `src/add/add-channel.ts` line 360: `shorthandDecl.name.getText()` -> `.text` (ImportSpecifier name is always Identifier)
+
+**Skip** (not safe or rarely hit): error messages, template literals, TypeNode, QualifiedName.
+
+**Measure:** "Visit setup phase" + "Visit routes phase" timings.
+
+**Expected improvement:** 1-3% of visit phases.
+
+**Verify:** `bash run-tests.sh`
+
+---
+
+## Step 4: Replace `JSON.parse(JSON.stringify(...))` with `structuredClone()`
+
+**File:** `src/utils/filter-inspector-state.ts` (lines 198-233)
+
+**Problem:** 8 calls to `JSON.parse(JSON.stringify(...))` for deep cloning metadata objects. This serializes to string then parses back -- wasteful.
+
+**Fix:** Replace all 8 with `structuredClone()` (available Node 17+, package requires >=18).
+
+```ts
+// Before
+meta: JSON.parse(JSON.stringify(state.http.meta))
+// After
+meta: structuredClone(state.http.meta)
+```
+
+**Measure:** Separate `filterInspectorState` benchmark loop using the 45KB test fixture.
+
+**Expected improvement:** 10-30% of filter phase time (not the main inspect path, but important for CLI).
+
+**Verify:** `bash run-tests.sh` (filter-inspector-state.test.ts covers this extensively -- 1,440 lines of tests).
+
+---
+
+## Step 5: Cache `node.getSourceFile().fileName` in Hot Handlers
+
+**Files:** Primarily `src/add/add-functions.ts`
+
+**Problem:** `add-functions.ts` calls `node.getSourceFile().fileName` 4+ times within a single handler invocation for the same node (lines 666, 700, 721, 735). `getSourceFile()` walks the parent chain each time.
+
+**Fix:** Extract once at handler entry:
+
+```ts
+const sourceFileName = node.getSourceFile().fileName
+```
+
+Then reuse `sourceFileName` throughout.
+
+**Measure:** "Visit routes phase" timing.
+
+**Expected improvement:** 1-2%.
+
+**Verify:** `bash run-tests.sh`
+
+---
+
+## Summary
+
+| Step | Change            | File(s)                     | Expected Impact            | Metric               |
+| ---- | ----------------- | --------------------------- | -------------------------- | -------------------- |
+| 0    | Benchmark harness | New `benchmark.ts`          | Baseline                   | -                    |
+| 1    | Dispatch map      | `visit.ts`                  | **30-60%** of visit phases | Visit setup + routes |
+| 2    | Hoist regex       | `add-functions.ts`          | 1-5% of visit routes       | Visit routes         |
+| 3    | getText -> .text  | 3-5 files                   | 1-3% of visit phases       | Visit setup + routes |
+| 4    | structuredClone   | `filter-inspector-state.ts` | 10-30% of filter phase     | Filter benchmark     |
+| 5    | Cache sourceFile  | `add-functions.ts`          | 1-2% of visit routes       | Visit routes         |
+
+## Verification
+
+After each step:
+
+1. Run benchmark: `node --import tsx src/benchmark.ts <target> 10`
+2. Run tests: `cd packages/inspector && bash run-tests.sh`
+3. Compare serialized inspector state output (before vs after) to confirm identical results

package/dist/add/add-ai-agent.d.ts

@@ -0,0 +1,2 @@
+import { AddWiring } from '../types.js';
+export declare const addAIAgent: AddWiring;

package/dist/add/add-ai-agent.js

@@ -0,0 +1,314 @@
+import * as ts from 'typescript';
+import { getPropertyValue, getCommonWireMetaData, } from '../utils/get-property-value.js';
+import { extractWireNames } from '../utils/post-process.js';
+import { extractFunctionName, funcIdToTypeName, } from '../utils/extract-function-name.js';
+import { resolveMiddleware, resolveChannelMiddleware, resolveAIMiddleware, } from '../utils/middleware.js';
+import { resolvePermissions } from '../utils/permissions.js';
+import { ErrorCode } from '../error-codes.js';
+import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
+function resolveToolReferences(obj, checker, agentName, logger) {
+    const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'tools');
+    if (!property || !ts.isPropertyAssignment(property)) {
+        return null;
+    }
+    const initializer = property.initializer;
+    if (!ts.isArrayLiteralExpression(initializer)) {
+        return null;
+    }
+    const resolved = [];
+    for (const element of initializer.elements) {
+        if (ts.isStringLiteral(element)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `AI agent '${agentName}' tools array contains a string literal '${element.text}'. ` +
+                `Use a function reference instead (e.g., import the pikkuFunc variable).`);
+            continue;
+        }
+        if (ts.isCallExpression(element) && ts.isIdentifier(element.expression)) {
+            const calleeName = element.expression.text;
+            if (calleeName === 'workflow') {
+                const [firstArg] = element.arguments;
+                if (firstArg && ts.isStringLiteral(firstArg)) {
+                    resolved.push(`workflow:${firstArg.text}`);
+                    continue;
+                }
+            }
+            if (calleeName === 'external') {
+                const [firstArg] = element.arguments;
+                if (firstArg && ts.isStringLiteral(firstArg)) {
+                    resolved.push(firstArg.text);
+                    continue;
+                }
+            }
+        }
+        if (ts.isIdentifier(element)) {
+            const rpcName = resolveIdentifierToRpcName(element, checker);
+            if (rpcName) {
+                resolved.push(rpcName);
+                continue;
+            }
+            logger.critical(ErrorCode.INVALID_VALUE, `AI agent '${agentName}' tools array contains identifier '${element.text}' ` +
+                `that could not be resolved to a pikkuFunc.`);
+        }
+    }
+    return resolved.length > 0 ? resolved : null;
+}
+function resolveAgentReferences(obj, checker, agentName, logger) {
+    const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'agents');
+    if (!property || !ts.isPropertyAssignment(property)) {
+        return null;
+    }
+    const initializer = property.initializer;
+    if (!ts.isArrayLiteralExpression(initializer)) {
+        return null;
+    }
+    const resolved = [];
+    for (const element of initializer.elements) {
+        if (ts.isStringLiteral(element)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `AI agent '${agentName}' agents array contains a string literal '${element.text}'. ` +
+                `Use an agent reference instead (e.g., import the pikkuAIAgent variable).`);
+            continue;
+        }
+        if (ts.isIdentifier(element)) {
+            const name = resolveIdentifierToAgentName(element, checker);
+            if (name) {
+                resolved.push(name);
+                continue;
+            }
+            logger.critical(ErrorCode.INVALID_VALUE, `AI agent '${agentName}' agents array contains identifier '${element.text}' ` +
+                `that could not be resolved to a pikkuAIAgent.`);
+        }
+    }
+    return resolved.length > 0 ? resolved : null;
+}
+function resolveIdentifierToRpcName(identifier, checker) {
+    const symbol = checker.getSymbolAtLocation(identifier);
+    if (!symbol)
+        return null;
+    let resolved = symbol;
+    if (resolved.flags & ts.SymbolFlags.Alias) {
+        resolved = checker.getAliasedSymbol(resolved) ?? resolved;
+    }
+    const decl = resolved.valueDeclaration ?? resolved.declarations?.[0];
+    if (!decl)
+        return null;
+    if (ts.isVariableDeclaration(decl) && decl.initializer) {
+        if (ts.isCallExpression(decl.initializer) &&
+            ts.isIdentifier(decl.initializer.expression)) {
+            const callName = decl.initializer.expression.text;
+            if (callName === 'pikkuFunc' ||
+                callName === 'pikkuSessionlessFunc' ||
+                callName === 'pikkuVoidFunc') {
+                const firstArg = decl.initializer.arguments[0];
+                if (firstArg && ts.isObjectLiteralExpression(firstArg)) {
+                    for (const prop of firstArg.properties) {
+                        if (ts.isPropertyAssignment(prop) &&
+                            ts.isIdentifier(prop.name) &&
+                            prop.name.text === 'override' &&
+                            ts.isStringLiteral(prop.initializer)) {
+                            return prop.initializer.text;
+                        }
+                    }
+                }
+                if (ts.isIdentifier(decl.name)) {
+                    return decl.name.text;
+                }
+            }
+        }
+    }
+    return null;
+}
+function resolveIdentifierToAgentName(identifier, checker) {
+    const symbol = checker.getSymbolAtLocation(identifier);
+    if (!symbol)
+        return null;
+    let resolved = symbol;
+    if (resolved.flags & ts.SymbolFlags.Alias) {
+        resolved = checker.getAliasedSymbol(resolved) ?? resolved;
+    }
+    const decl = resolved.valueDeclaration ?? resolved.declarations?.[0];
+    if (!decl)
+        return null;
+    if (ts.isVariableDeclaration(decl) && decl.initializer) {
+        if (ts.isCallExpression(decl.initializer) &&
+            ts.isIdentifier(decl.initializer.expression) &&
+            decl.initializer.expression.text === 'pikkuAIAgent') {
+            if (ts.isIdentifier(decl.name)) {
+                return decl.name.text;
+            }
+        }
+    }
+    return null;
+}
+export const addAIAgent = (logger, node, checker, state, options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const args = node.arguments;
+    const firstArg = args[0];
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuAIAgent') {
+        return;
+    }
+    if (!firstArg) {
+        return;
+    }
+    const { exportedName } = extractFunctionName(node, checker, state.rootDir);
+    if (ts.isObjectLiteralExpression(firstArg)) {
+        const obj = firstArg;
+        const nameValue = getPropertyValue(obj, 'name');
+        const { disabled, tags, summary, description, errors } = getCommonWireMetaData(obj, 'AI agent', nameValue, logger);
+        if (disabled)
+            return;
+        const modelValue = getPropertyValue(obj, 'model');
+        const instructionsValue = getPropertyValue(obj, 'instructions');
+        const maxStepsValue = getPropertyValue(obj, 'maxSteps');
+        const temperatureValue = getPropertyValue(obj, 'temperature');
+        const toolChoiceValue = getPropertyValue(obj, 'toolChoice');
+        const toolsValue = resolveToolReferences(obj, checker, nameValue || '', logger);
+        if (toolsValue) {
+            for (const toolName of toolsValue) {
+                if (toolName.startsWith('workflow:') || toolName.includes(':'))
+                    continue;
+                const funcFile = state.functions.files.get(toolName);
+                if (funcFile && !state.rpc.internalFiles.has(toolName)) {
+                    state.rpc.internalFiles.set(toolName, funcFile);
+                }
+            }
+        }
+        const agentsValue = resolveAgentReferences(obj, checker, nameValue || '', logger);
+        if (!nameValue) {
+            logger.critical(ErrorCode.MISSING_NAME, "AI agent is missing the required 'name' property.");
+            return;
+        }
+        const agentKey = exportedName || nameValue;
+        if (!description) {
+            logger.critical(ErrorCode.MISSING_DESCRIPTION, `AI agent '${nameValue}' is missing a description.`);
+            return;
+        }
+        const resolveSchemaRef = (identifier, context) => {
+            const symbol = checker.getSymbolAtLocation(identifier);
+            if (!symbol)
+                return null;
+            const decl = symbol.valueDeclaration || symbol.declarations?.[0];
+            if (!decl)
+                return null;
+            let sourceFile;
+            if (ts.isImportSpecifier(decl)) {
+                const aliasedSymbol = checker.getAliasedSymbol(symbol);
+                if (aliasedSymbol) {
+                    const aliasedDecl = aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0];
+                    if (aliasedDecl) {
+                        sourceFile = aliasedDecl.getSourceFile().fileName;
+                    }
+                    else {
+                        return null;
+                    }
+                }
+                else {
+                    return null;
+                }
+            }
+            else {
+                sourceFile = decl.getSourceFile().fileName;
+            }
+            const vendor = detectSchemaVendorOrError(identifier, checker, logger, context, sourceFile);
+            if (!vendor)
+                return null;
+            return {
+                variableName: identifier.text,
+                sourceFile,
+                vendor,
+            };
+        };
+        let inputSchema = null;
+        let outputSchema = null;
+        let workingMemorySchema = null;
+        const capitalizedName = funcIdToTypeName(agentKey);
+        for (const prop of obj.properties) {
+            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                const propName = prop.name.text;
+                if (propName === 'input' || propName === 'output') {
+                    if (ts.isIdentifier(prop.initializer)) {
+                        const context = `AI agent '${nameValue}' ${propName}`;
+                        const ref = resolveSchemaRef(prop.initializer, context);
+                        if (ref) {
+                            const schemaName = `${capitalizedName}${propName.charAt(0).toUpperCase() + propName.slice(1)}`;
+                            state.schemaLookup.set(schemaName, ref);
+                            state.functions.typesMap.addCustomType(schemaName, 'unknown', []);
+                            if (propName === 'input') {
+                                inputSchema = schemaName;
+                            }
+                            else {
+                                outputSchema = schemaName;
+                            }
+                        }
+                    }
+                    else if (ts.isCallExpression(prop.initializer)) {
+                        const schemaName = `${capitalizedName}${propName.charAt(0).toUpperCase() + propName.slice(1)}`;
+                        logger.critical(ErrorCode.INLINE_SCHEMA, `Inline schemas are not supported for '${propName}' in AI agent '${nameValue}'.\n` +
+                            `  Extract to an exported variable:\n` +
+                            `    export const ${schemaName} = ${prop.initializer.getText()}\n` +
+                            `  Then use: ${propName}: ${schemaName}`);
+                    }
+                }
+                else if (propName === 'memory' &&
+                    ts.isObjectLiteralExpression(prop.initializer)) {
+                    for (const memProp of prop.initializer.properties) {
+                        if (ts.isPropertyAssignment(memProp) &&
+                            ts.isIdentifier(memProp.name) &&
+                            memProp.name.text === 'workingMemory' &&
+                            ts.isIdentifier(memProp.initializer)) {
+                            const context = `AI agent '${nameValue}' workingMemory`;
+                            const ref = resolveSchemaRef(memProp.initializer, context);
+                            if (ref) {
+                                const schemaName = `${capitalizedName}WorkingMemory`;
+                                state.schemaLookup.set(schemaName, ref);
+                                state.functions.typesMap.addCustomType(schemaName, 'unknown', []);
+                                workingMemorySchema = schemaName;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const middleware = resolveMiddleware(state, obj, tags, checker);
+        const channelMiddleware = resolveChannelMiddleware(state, obj, tags, checker);
+        const aiMiddleware = resolveAIMiddleware(state, obj, checker);
+        const permissions = resolvePermissions(state, obj, tags, checker);
+        state.serviceAggregation.usedFunctions.add(agentKey);
+        extractWireNames(middleware).forEach((name) => state.serviceAggregation.usedMiddleware.add(name));
+        extractWireNames(permissions).forEach((name) => state.serviceAggregation.usedPermissions.add(name));
+        if (exportedName) {
+            state.agents.files.set(agentKey, {
+                path: node.getSourceFile().fileName,
+                exportedName,
+            });
+        }
+        state.agents.agentsMeta[agentKey] = {
+            name: nameValue,
+            description,
+            instructions: instructionsValue || '',
+            model: modelValue || '',
+            summary,
+            errors,
+            ...(maxStepsValue !== null && { maxSteps: maxStepsValue }),
+            ...(temperatureValue !== null && { temperature: temperatureValue }),
+            ...(toolChoiceValue !== null && {
+                toolChoice: toolChoiceValue,
+            }),
+            ...(toolsValue !== null && { tools: toolsValue }),
+            ...(agentsValue !== null && { agents: agentsValue }),
+            tags,
+            inputSchema,
+            outputSchema,
+            workingMemorySchema,
+            middleware,
+            channelMiddleware,
+            aiMiddleware,
+            permissions,
+        };
+    }
+};