@pikku/inspector 0.12.72 → 0.12.73

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.12.73
+
+### Patch Changes
+
+- 6519c66: Report what each inspector pass did, not only how long it took. `inspect()` now records per-pass work counters on the state (`stats`: files in the program, files reused from the previous program, type/instantiation/symbol counts, CPU and wall time, heap in use), and `pikku all` prints one `[INSPECT]` row per pass under `PIKKU_TIMING`. The codegen benchmark gates on those counts and on live heap per pass instead of on step timings, which swing with the runner, and its fixture now includes an agent so the post-agent re-inspection is actually exercised.
+- 5447dba: Keep parsed source files across inspector passes. A re-inspection in `pikku all` used to re-parse and re-bind every file, because the previous `ts.Program` — the thing TypeScript reuses parses from — had to be dropped to free its type checker. The inspector now builds each program through a compiler host with a content-hashed `SourceFile` cache, so a re-inspection parses only what codegen just wrote while holding no checker: on the 500-function benchmark the re-inspection reuses all 908 files, its CPU time falls by a third, and peak heap drops.
+
 ## 0.12.72
 
 ### Patch Changes

package/dist/inspector.js

@@ -5,6 +5,7 @@ import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
+import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
@@ -273,10 +274,13 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         allowJs: false,
         checkJs: false,
     };
+    const cpuStart = process.cpuUsage();
     const startProgram = performance.now();
-    const program = ts.createProgram(normalizedRouteFiles, compilerOptions, undefined, // host
-    options.oldProgram);
-    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files${options.oldProgram ? ', incremental' : ''})`);
+    const host = createSourceFileCacheHost(compilerOptions);
+    const program = ts.createProgram(normalizedRouteFiles, compilerOptions, host, options.oldProgram);
+    host.prune(program);
+    const filesReused = host.reused();
+    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files, ${filesReused} source files reused)`);
     const startChecker = performance.now();
     const checker = program.getTypeChecker();
     logger.debug(`Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`);
@@ -417,6 +421,18 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validatePersonaRoles(logger, state);
         logger.endValidationPass?.();
     }
+    const cpu = process.cpuUsage(cpuStart);
+    state.stats = {
+        files: program.getSourceFiles().length,
+        projectFiles: sourceFiles.length,
+        filesReused,
+        types: program.getTypeCount(),
+        instantiations: program.getInstantiationCount(),
+        symbols: program.getSymbolCount(),
+        cpuMs: Math.round((cpu.user + cpu.system) / 1000),
+        wallMs: Math.round(performance.now() - startProgram),
+        heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
+    };
     state.program = program;
     return state;
 };

package/dist/source-file-cache.d.ts

@@ -0,0 +1,11 @@
+import * as ts from 'typescript';
+export interface SourceFileCacheHost extends ts.CompilerHost {
+    /** Files served from the cache by the program just built. */
+    readonly reused: () => number;
+    /**
+     * Drop entries the program did not use, so a file that left the project
+     * (or watch mode's churn) does not pin its AST forever.
+     */
+    readonly prune: (program: ts.Program) => void;
+}
+export declare const createSourceFileCacheHost: (options: ts.CompilerOptions) => SourceFileCacheHost;

package/dist/source-file-cache.js

@@ -0,0 +1,54 @@
+import * as ts from 'typescript';
+import { createHash } from 'crypto';
+/**
+ * Parsed source files, kept across programs so a re-inspection only re-parses
+ * what changed. Keyed by path; an entry is valid while the file's content
+ * hash matches.
+ *
+ * This is the incremental reuse `oldProgram` used to give, without its cost.
+ * Passing the previous ts.Program keeps that program reachable, and a program
+ * memoises its type checker — so every re-inspection held a second, fully
+ * exercised checker for the sake of skipping a re-parse. A bare SourceFile
+ * carries its AST and binder symbols and nothing else; sharing it between
+ * programs is what the language service's document registry does.
+ *
+ * Module-level on purpose: `inspect()` is called several times per `pikku all`
+ * (and indefinitely in watch mode) from one process, and the cache is only
+ * worth having if it outlives the call.
+ */
+const cache = new Map();
+export const createSourceFileCacheHost = (options) => {
+    const host = ts.createCompilerHost(options, true);
+    let reused = 0;
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+        let text;
+        try {
+            text = host.readFile(fileName);
+        }
+        catch (e) {
+            onError?.(e instanceof Error ? e.message : String(e));
+            return undefined;
+        }
+        if (text === undefined)
+            return undefined;
+        const hash = createHash('sha1').update(text).digest('hex');
+        const hit = cache.get(fileName);
+        if (hit && hit.hash === hash) {
+            reused++;
+            return hit.file;
+        }
+        const file = ts.createSourceFile(fileName, text, languageVersionOrOptions, true);
+        cache.set(fileName, { hash, file });
+        return file;
+    };
+    return Object.assign(host, {
+        reused: () => reused,
+        prune: (program) => {
+            const live = new Set(program.getSourceFiles().map((sf) => sf.fileName));
+            for (const fileName of cache.keys()) {
+                if (!live.has(fileName))
+                    cache.delete(fileName);
+            }
+        },
+    });
+};

package/dist/types.d.ts

@@ -223,6 +223,26 @@ export type AddonConfig = {
     secretOverrides?: Record<string, string>;
     forceInclude?: boolean;
 };
+export interface InspectorPassStats {
+    /** Source files in the ts.Program, node_modules and lib included. */
+    files: number;
+    /** Files under rootDir the inspector actually swept. */
+    projectFiles: number;
+    /**
+     * Files served from the source-file cache without re-parsing. Zero on a
+     * first pass; on a re-inspection it should be nearly all of `files` — that
+     * reuse is what keeps a re-inspection cheaper than a cold one.
+     */
+    filesReused: number;
+    /** Checker work, as `tsc --extendedDiagnostics` counts it. */
+    types: number;
+    instantiations: number;
+    symbols: number;
+    cpuMs: number;
+    wallMs: number;
+    /** V8 heap in use when the pass finished, before any GC. */
+    heapUsedMb: number;
+}
 export type InspectorOptions = Partial<{
     setupOnly: boolean;
     rootDir: string;
@@ -456,6 +476,12 @@ export interface InspectorState {
     filesAndMethods: InspectorFilesAndMethods;
     filesAndMethodsErrors: Map<string, PathToNameAndType>;
     typesLookup: Map<string, ts.Type[]>;
+    /**
+     * What this pass cost, in counts rather than time where it can be counted:
+     * counts don't move with the machine, so they are what a perf gate can
+     * compare across runners (see benchmarks/bench-codegen-perf.ts).
+     */
+    stats?: InspectorPassStats;
     schemaLookup: Map<string, SchemaRef>;
     schemas: Record<string, JSONValue>;
     http: InspectorHTTPState;

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

@@ -914,8 +914,21 @@ export function filterInspectorState(state, filters, logger) {
             for (const tool of agentMeta.tools ?? [])
                 referencedIds.add(tool);
         }
+        // A unit carrying the generic `/rpc/:rpcName` catch-all (the rpcCaller
+        // unit, and agent units) dispatches arbitrary RPCs at runtime via
+        // `rpc.exposed(name)`, including namespaced addon RPCs (e.g.
+        // `admin:createUser`). Those never appear in referencedIds because no
+        // app-local function statically references them, so keep every wired
+        // addon's declaration for such units — otherwise the per-unit bootstrap
+        // omits the addon package bootstrap and `rpc.exposed('admin:createUser')`
+        // throws RPCNotFoundError on the deployed stage.
+        const hasRpcCatchAll = (filters.names ?? []).includes('/rpc/:rpcName');
         const keptNamespaces = new Set();
         for (const namespace of filteredState.rpc.wireAddonDeclarations.keys()) {
+            if (hasRpcCatchAll) {
+                keptNamespaces.add(namespace);
+                continue;
+            }
             const prefix = `${namespace}:`;
             for (const id of referencedIds) {
                 if (id.startsWith(prefix)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.72",
+  "version": "0.12.73",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",

package/src/inspector.ts

@@ -10,6 +10,7 @@ import type {
 } from './types.js'
 import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
+import { createSourceFileCacheHost } from './source-file-cache.js'
 import { createNestedProjectFilter } from './utils/nested-project-filter.js'
 import {
   aggregateRequiredServices,
@@ -335,15 +336,19 @@ export const inspect = async (
     allowJs: false,
     checkJs: false,
   }
+  const cpuStart = process.cpuUsage()
   const startProgram = performance.now()
+  const host = createSourceFileCacheHost(compilerOptions)
   const program = ts.createProgram(
     normalizedRouteFiles,
     compilerOptions,
-    undefined, // host
+    host,
     options.oldProgram
   )
+  host.prune(program)
+  const filesReused = host.reused()
   logger.debug(
-    `Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files${options.oldProgram ? ', incremental' : ''})`
+    `Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files, ${filesReused} source files reused)`
   )
 
   const startChecker = performance.now()
@@ -552,6 +557,18 @@ export const inspect = async (
     logger.endValidationPass?.()
   }
 
+  const cpu = process.cpuUsage(cpuStart)
+  state.stats = {
+    files: program.getSourceFiles().length,
+    projectFiles: sourceFiles.length,
+    filesReused,
+    types: program.getTypeCount(),
+    instantiations: program.getInstantiationCount(),
+    symbols: program.getSymbolCount(),
+    cpuMs: Math.round((cpu.user + cpu.system) / 1000),
+    wallMs: Math.round(performance.now() - startProgram),
+    heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
+  }
   state.program = program
 
   return state

package/src/source-file-cache.ts

@@ -0,0 +1,73 @@
+import * as ts from 'typescript'
+import { createHash } from 'crypto'
+
+/**
+ * Parsed source files, kept across programs so a re-inspection only re-parses
+ * what changed. Keyed by path; an entry is valid while the file's content
+ * hash matches.
+ *
+ * This is the incremental reuse `oldProgram` used to give, without its cost.
+ * Passing the previous ts.Program keeps that program reachable, and a program
+ * memoises its type checker — so every re-inspection held a second, fully
+ * exercised checker for the sake of skipping a re-parse. A bare SourceFile
+ * carries its AST and binder symbols and nothing else; sharing it between
+ * programs is what the language service's document registry does.
+ *
+ * Module-level on purpose: `inspect()` is called several times per `pikku all`
+ * (and indefinitely in watch mode) from one process, and the cache is only
+ * worth having if it outlives the call.
+ */
+const cache = new Map<string, { hash: string; file: ts.SourceFile }>()
+
+export interface SourceFileCacheHost extends ts.CompilerHost {
+  /** Files served from the cache by the program just built. */
+  readonly reused: () => number
+  /**
+   * Drop entries the program did not use, so a file that left the project
+   * (or watch mode's churn) does not pin its AST forever.
+   */
+  readonly prune: (program: ts.Program) => void
+}
+
+export const createSourceFileCacheHost = (
+  options: ts.CompilerOptions
+): SourceFileCacheHost => {
+  const host = ts.createCompilerHost(options, true)
+  let reused = 0
+
+  host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+    let text: string | undefined
+    try {
+      text = host.readFile(fileName)
+    } catch (e) {
+      onError?.(e instanceof Error ? e.message : String(e))
+      return undefined
+    }
+    if (text === undefined) return undefined
+
+    const hash = createHash('sha1').update(text).digest('hex')
+    const hit = cache.get(fileName)
+    if (hit && hit.hash === hash) {
+      reused++
+      return hit.file
+    }
+    const file = ts.createSourceFile(
+      fileName,
+      text,
+      languageVersionOrOptions,
+      true
+    )
+    cache.set(fileName, { hash, file })
+    return file
+  }
+
+  return Object.assign(host, {
+    reused: () => reused,
+    prune: (program: ts.Program) => {
+      const live = new Set(program.getSourceFiles().map((sf) => sf.fileName))
+      for (const fileName of cache.keys()) {
+        if (!live.has(fileName)) cache.delete(fileName)
+      }
+    },
+  })
+}

package/src/types.ts

@@ -290,6 +290,27 @@ export type AddonConfig = {
   forceInclude?: boolean
 }
 
+export interface InspectorPassStats {
+  /** Source files in the ts.Program, node_modules and lib included. */
+  files: number
+  /** Files under rootDir the inspector actually swept. */
+  projectFiles: number
+  /**
+   * Files served from the source-file cache without re-parsing. Zero on a
+   * first pass; on a re-inspection it should be nearly all of `files` — that
+   * reuse is what keeps a re-inspection cheaper than a cold one.
+   */
+  filesReused: number
+  /** Checker work, as `tsc --extendedDiagnostics` counts it. */
+  types: number
+  instantiations: number
+  symbols: number
+  cpuMs: number
+  wallMs: number
+  /** V8 heap in use when the pass finished, before any GC. */
+  heapUsedMb: number
+}
+
 export type InspectorOptions = Partial<{
   setupOnly: boolean
   rootDir: string
@@ -534,6 +555,12 @@ export interface InspectorState {
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
   typesLookup: Map<string, ts.Type[]> // Lookup for types by name (e.g., function input types, Config type)
+  /**
+   * What this pass cost, in counts rather than time where it can be counted:
+   * counts don't move with the machine, so they are what a perf gate can
+   * compare across runners (see benchmarks/bench-codegen-perf.ts).
+   */
+  stats?: InspectorPassStats
   schemaLookup: Map<string, SchemaRef> // Lookup for schemas by name for deferred JSON Schema conversion (supports Standard Schema vendors)
   schemas: Record<string, JSONValue>
   http: InspectorHTTPState

package/src/utils/filter-inspector-state.test.ts

@@ -2141,4 +2141,67 @@ describe('invokedAgentsByFile', () => {
       ['/test/project/src/api/users.ts']
     )
   })
+
+  describe('Wired addon retention', () => {
+    // A unit that owns the generic `/rpc/:rpcName` catch-all (the rpcCaller
+    // unit, and agent units) dispatches arbitrary RPCs at runtime via
+    // `rpc.exposed(name)`, including namespaced addon RPCs like
+    // `admin:createUser`. No app-local function statically references those
+    // ids, so the catch-all must be enough to keep every wired addon's
+    // declaration — otherwise the per-unit bootstrap omits the addon package
+    // bootstrap and `rpc.exposed('admin:createUser')` throws RPCNotFoundError
+    // on a deployed stage.
+    const withAddons = () => {
+      const state = createMockInspectorState()
+      state.rpc.wireAddonDeclarations = new Map([
+        ['admin', { package: '@pikku/addon-admin' } as any],
+        ['console', { package: '@pikku/addon-console' } as any],
+      ])
+      state.rpc.usedAddons = new Set(['admin', 'console'])
+      return state
+    }
+
+    test('keeps all wired addons for a unit with the /rpc/:rpcName catch-all', () => {
+      const result = filterInspectorState(
+        withAddons(),
+        { names: ['/rpc/:rpcName', 'http:post:/rpc/:rpcName', 'rpcCaller'] },
+        mockLogger
+      )
+      assert.deepStrictEqual(
+        [...result.rpc.wireAddonDeclarations.keys()].sort(),
+        ['admin', 'console']
+      )
+      assert.deepStrictEqual([...result.rpc.usedAddons].sort(), [
+        'admin',
+        'console',
+      ])
+    })
+
+    test('drops wired addons for a unit without the catch-all that references no namespace', () => {
+      const result = filterInspectorState(
+        withAddons(),
+        { names: ['getUsers'] },
+        mockLogger
+      )
+      assert.deepStrictEqual([...result.rpc.wireAddonDeclarations.keys()], [])
+      assert.deepStrictEqual([...result.rpc.usedAddons], [])
+    })
+
+    test('still keeps an addon a surviving function statically references, without the catch-all', () => {
+      const state = withAddons()
+      state.serviceAggregation.usedFunctions.add('getUsers')
+      state.rpc.invokedFunctionsByFile = new Map([
+        ['/test/project/src/api/users.ts', new Set(['admin:createUser'])],
+      ])
+      const result = filterInspectorState(
+        state,
+        { names: ['getUsers'] },
+        mockLogger
+      )
+      assert.deepStrictEqual(
+        [...result.rpc.wireAddonDeclarations.keys()],
+        ['admin']
+      )
+    })
+  })
 })

package/src/utils/filter-inspector-state.ts

@@ -1258,8 +1258,21 @@ export function filterInspectorState(
     ) as Array<{ tools?: string[] }>) {
       for (const tool of agentMeta.tools ?? []) referencedIds.add(tool)
     }
+    // A unit carrying the generic `/rpc/:rpcName` catch-all (the rpcCaller
+    // unit, and agent units) dispatches arbitrary RPCs at runtime via
+    // `rpc.exposed(name)`, including namespaced addon RPCs (e.g.
+    // `admin:createUser`). Those never appear in referencedIds because no
+    // app-local function statically references them, so keep every wired
+    // addon's declaration for such units — otherwise the per-unit bootstrap
+    // omits the addon package bootstrap and `rpc.exposed('admin:createUser')`
+    // throws RPCNotFoundError on the deployed stage.
+    const hasRpcCatchAll = (filters.names ?? []).includes('/rpc/:rpcName')
     const keptNamespaces = new Set<string>()
     for (const namespace of filteredState.rpc.wireAddonDeclarations.keys()) {
+      if (hasRpcCatchAll) {
+        keptNamespaces.add(namespace)
+        continue
+      }
       const prefix = `${namespace}:`
       for (const id of referencedIds) {
         if (id.startsWith(prefix)) {