@pikku/inspector 0.12.75 → 0.12.81

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

@@ -935,6 +935,20 @@ export function filterInspectorState(state, filters, logger) {
         }
         filteredState.rpc.wireAddonDeclarations = new Map([...filteredState.rpc.wireAddonDeclarations].filter(([namespace]) => keptNamespaces.has(namespace)));
         filteredState.rpc.usedAddons = new Set([...filteredState.rpc.usedAddons].filter((namespace) => keptNamespaces.has(namespace)));
+        const keptAddonFiles = new Set();
+        for (const decl of filteredState.rpc.wireAddonDeclarations.values()) {
+            if (decl.file)
+                keptAddonFiles.add(decl.file);
+        }
+        const droppedAddonFiles = new Set();
+        for (const [namespace, decl] of state.rpc.wireAddonDeclarations) {
+            if (keptNamespaces.has(namespace))
+                continue;
+            if (decl.file && !keptAddonFiles.has(decl.file)) {
+                droppedAddonFiles.add(decl.file);
+            }
+        }
+        filteredState.rpc.wireAddonFiles = new Set([...(filteredState.rpc.wireAddonFiles ?? [])].filter((file) => !droppedAddonFiles.has(file)));
     }
     // Recalculate requiredServices based on filtered functions/middleware/permissions
     // Need to cast to InspectorState temporarily for aggregateRequiredServices

package/dist/utils/post-process.js

@@ -271,6 +271,21 @@ export function aggregateRequiredServices(state) {
     if ((state.scopes?.definitions?.length ?? 0) > 0) {
         requiredServices.add('scopeService');
     }
+    // Declared feature flags need featureFlags for the same reason, from the
+    // other side: `assertFeatureAvailable` reads the source out of the singleton
+    // services itself, so a `featureFlag:` on a wiring is the only thing that
+    // ever says the project has flags. Without this the flag tables are left out
+    // of the generated migration and every gate silently resolves open.
+    if ((state.featureFlags?.definitions?.length ?? 0) > 0) {
+        requiredServices.add('featureFlags');
+    }
+    // A `defineAnalyticsEvents` declaration means events are emitted, and the
+    // invocation buffer flushes into `analyticsService`. Nothing destructures
+    // that either — functions are handed the request-scoped `analytics` — so the
+    // declaration is again the only signal.
+    if ((state.analytics?.length ?? 0) > 0) {
+        requiredServices.add('analyticsService');
+    }
     // 7. Services that consumed addons need from the parent project.
     const addonFnServices = new Map();
     for (const [namespace, fns] of Object.entries(state.addonFunctions ?? {})) {

package/dist/utils/read-module-specifiers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The module specifiers a source file imports from or re-exports from.
+ *
+ * Parsed rather than grepped: a project's own codegen templates hold the
+ * specifiers they emit inside template literals, and those are output text
+ * rather than imports the file itself makes.
+ */
+export declare const readModuleSpecifiers: (fileName: string, content: string) => string[];

package/dist/utils/read-module-specifiers.js

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+/**
+ * The module specifiers a source file imports from or re-exports from.
+ *
+ * Parsed rather than grepped: a project's own codegen templates hold the
+ * specifiers they emit inside template literals, and those are output text
+ * rather than imports the file itself makes.
+ */
+export const readModuleSpecifiers = (fileName, content) => {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+    const found = [];
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) &&
+            !ts.isExportDeclaration(statement)) {
+            continue;
+        }
+        const moduleSpecifier = statement.moduleSpecifier;
+        if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier))
+            continue;
+        found.push(moduleSpecifier.text);
+    }
+    return found;
+};

package/dist/utils/read-tsconfig-out-dir.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A tsconfig's resolved `compilerOptions.outDir`, or undefined when it sets
+ * none. Resolved through the compiler so `extends` chains are followed.
+ */
+export declare const readTsconfigOutDir: (tsconfig: string) => string | undefined;

package/dist/utils/read-tsconfig-out-dir.js

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+/**
+ * A tsconfig's resolved `compilerOptions.outDir`, or undefined when it sets
+ * none. Resolved through the compiler so `extends` chains are followed.
+ */
+export const readTsconfigOutDir = (tsconfig) => {
+    const parsed = ts.getParsedCommandLineOfConfigFile(tsconfig, {}, {
+        ...ts.sys,
+        onUnRecoverableConfigFileDiagnostic: () => { },
+    });
+    return parsed?.options.outDir;
+};

package/dist/utils/resolve-deploy-target.d.ts

@@ -10,6 +10,13 @@ export declare class IncompatibleDeployTargetError extends Error {
     readonly incompatibleServices: string[];
     constructor(functionName: string, incompatibleServices: string[]);
 }
+/**
+ * The function's services that are declared `serverlessIncompatible`. A
+ * non-empty result is exactly the condition that crosses a function to
+ * 'server', so callers that need to explain a target — rather than only
+ * resolve it — read the reason from here.
+ */
+export declare function incompatibleServicesFor(funcMeta: Pick<FunctionMeta, 'services'>, serverlessIncompatible: Set<string>): string[];
 /**
  * Determine the effective deploy target for a function.
  *

package/dist/utils/resolve-deploy-target.js

@@ -17,6 +17,20 @@ export class IncompatibleDeployTargetError extends Error {
         this.name = 'IncompatibleDeployTargetError';
     }
 }
+/**
+ * The function's services that are declared `serverlessIncompatible`. A
+ * non-empty result is exactly the condition that crosses a function to
+ * 'server', so callers that need to explain a target — rather than only
+ * resolve it — read the reason from here.
+ */
+export function incompatibleServicesFor(funcMeta, serverlessIncompatible) {
+    const hits = [];
+    for (const svc of funcMeta.services?.services ?? []) {
+        if (serverlessIncompatible.has(svc))
+            hits.push(svc);
+    }
+    return hits;
+}
 /**
  * Determine the effective deploy target for a function.
  *
@@ -36,13 +50,7 @@ export class IncompatibleDeployTargetError extends Error {
 export function resolveDeployTarget(funcMeta, serverlessIncompatible, functionName = '<unknown>', defaultTarget = 'serverless') {
     // Service compatibility wins over the explicit flag — a serverless
     // bundle of a function that needs (e.g.) node:fs would crash at runtime.
-    const incompatibleHits = [];
-    if (funcMeta.services?.services) {
-        for (const svc of funcMeta.services.services) {
-            if (serverlessIncompatible.has(svc))
-                incompatibleHits.push(svc);
-        }
-    }
+    const incompatibleHits = incompatibleServicesFor(funcMeta, serverlessIncompatible);
     if (incompatibleHits.length > 0) {
         if (funcMeta.deploy === 'serverless') {
             throw new IncompatibleDeployTargetError(functionName, incompatibleHits);

package/dist/utils/serialize-inspector-state.d.ts

@@ -189,6 +189,7 @@ export interface SerializableInspectorState {
             string,
             {
                 package: string;
+                file?: string;
                 rpcEndpoint?: string;
                 remote?: boolean;
                 hasAuth?: boolean;
@@ -258,6 +259,10 @@ export interface SerializableInspectorState {
         definitions: InspectorState['systemRoles']['definitions'];
         files: string[];
     };
+    featureFlags: {
+        definitions: InspectorState['featureFlags']['definitions'];
+        files: string[];
+    };
     personas: {
         definitions: InspectorState['personas']['definitions'];
         files: string[];

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

@@ -134,6 +134,10 @@ export function serializeInspectorState(state) {
             definitions: state.systemRoles.definitions,
             files: Array.from(state.systemRoles.files),
         },
+        featureFlags: {
+            definitions: state.featureFlags.definitions,
+            files: Array.from(state.featureFlags.files),
+        },
         personas: {
             definitions: state.personas.definitions,
             files: Array.from(state.personas.files),
@@ -315,6 +319,10 @@ export function deserializeInspectorState(data) {
             definitions: data.systemRoles?.definitions || [],
             files: new Set(data.systemRoles?.files || []),
         },
+        featureFlags: {
+            definitions: data.featureFlags?.definitions || [],
+            files: new Set(data.featureFlags?.files || []),
+        },
         personas: {
             definitions: data.personas?.definitions || [],
             files: new Set(data.personas?.files || []),

package/dist/visit.js

@@ -24,11 +24,13 @@ import { addSecret } from './add/add-secret.js';
 import { addCredential } from './add/add-credential.js';
 import { addScope } from './add/add-scope.js';
 import { addSystemRole } from './add/add-system-role.js';
+import { addFeatureFlag } from './add/add-feature-flag.js';
 import { addPersonas } from './add/add-personas.js';
 import { addVariable } from './add/add-variable.js';
 import { addWorkflowGraph } from './add/add-workflow-graph.js';
 import { addFeature } from './add/add-feature.js';
 import { addAgent } from './add/add-agent.js';
+import { addAnalytics } from './add/add-analytics.js';
 import { addAgentScorer } from './add/add-agent-scorer.js';
 import { addApprovalDescription } from './add/add-approval-description.js';
 export const visitSetup = (logger, checker, node, state, options) => {
@@ -40,6 +42,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addFileWithFactory(node, checker, state.wireServicesFactories, 'CreateWireServices', state);
     addFileWithFactory(node, checker, state.configFactories, 'CreateConfig');
     addFileWithFactory(node, checker, state.serverLifecycleFactories, 'ServerLifecycle');
+    addAnalytics(logger, node, checker, state);
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
     addWireRemoteAddon(node, state, logger);
@@ -73,6 +76,7 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     addCredential(logger, node, checker, state, nextOptions);
     addScope(logger, node, checker, state, nextOptions);
     addSystemRole(logger, node, checker, state, nextOptions);
+    addFeatureFlag(logger, node, checker, state, nextOptions);
     addPersonas(logger, node, checker, state, nextOptions);
     addVariable(logger, node, checker, state, nextOptions);
     addHTTPRoute(logger, node, checker, state, nextOptions);

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.75",
+  "version": "0.12.81",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/inspector"
+  },
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -18,6 +23,11 @@
       "import": "./dist/schema-generator.js",
       "default": "./dist/schema-generator.js"
     },
+    "./surface": {
+      "types": "./dist/surface/collect-surface.d.ts",
+      "import": "./dist/surface/collect-surface.js",
+      "default": "./dist/surface/collect-surface.js"
+    },
     "./workflow-graph": {
       "types": "./dist/utils/workflow/graph/index.d.ts",
       "import": "./dist/utils/workflow/graph/index.js",
@@ -28,11 +38,11 @@
     "tsc": "tsc",
     "build": "tsc -b",
     "ncu": "npx npm-check-updates -x '/.*glob.*/'",
-    "release": "yarn build && npm test",
+    "release": "bun run build && npm test",
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.4",
@@ -45,13 +55,13 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.107"
+    "@pikku/core": "^0.12.111"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.107",
+    "@pikku/core": "^0.12.111",
     "@types/node": "^24.13.3"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/run-tests.sh

@@ -34,20 +34,35 @@ files=($(find src -type f -name "*.test.ts"))
 # Check if any files matched the pattern
 if [ ${#files[@]} -eq 0 ]; then
   echo "No test files found matching pattern: $pattern"
+  if [ "${STRICT_TEST_DISCOVERY}" = "1" ]; then
+    exit 1
+  fi
   exit 0
 fi
 
-# Construct the node command
-node_cmd=(node --import tsx --expose-gc --test)
+# Construct the bun command
+#
+# --parallel gives every test file its own worker process, which is what node's
+# `--test` did. Several suites keep module-level caches (a TypeScript program, a
+# temp fixture directory) that a shared process would leak between files.
+#
+# --timeout because bun caps a test at 5s by default where node had no cap, and
+# the suites that build real TypeScript programs run well past that.
+bun_cmd=(bun test --parallel --timeout 120000)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then
-  node_cmd+=(--watch)
+  # --watch reruns in one process; parallel workers have nothing to watch.
+  bun_cmd=(bun test --watch --timeout 120000)
 fi
 
 if [ "$coverage_mode" = true ]; then
-  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  # --coverage-dir=. keeps lcov.info at the package root: CI merges every
+  # package's report by prefixing its SF paths with the file's own directory,
+  # so a nested coverage/ directory would re-root them one level too deep.
+  bun_cmd+=(--coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir=.)
+  export PIKKU_TEST_COVERAGE=1
 fi
 
-# Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"
+# Execute the bun command with the expanded list of files
+"${bun_cmd[@]}" "${files[@]}"

package/src/add/add-addon-bans.ts

@@ -1,85 +0,0 @@
-import * as ts from 'typescript'
-import type { AddWiring } from '../types.js'
-import { ErrorCode } from '../error-codes.js'
-
-/**
- * Wiring helpers an addon must not call. Addons declare contracts with the
- * define* helpers and export functions; the consuming app does the wiring via
- * refHTTP / refChannel / refCLI. Service declarations remain allowed.
- */
-const BANNED_WIRINGS = new Set([
-  'wireAddon',
-  'wireRemoteAddon',
-  'wireChannel',
-  'wireCLI',
-  'wireGateway',
-  'wireHTTP',
-  'wireHTTPRoutes',
-  'wireMCPPrompt',
-  'wireMCPResource',
-  'wireQueueWorker',
-  'wireScheduler',
-  'wireTrigger',
-  'wireTriggerSource',
-])
-
-const CONTRACT_DEFINERS = new Set([
-  'defineHTTPRoutes',
-  'defineChannelRoutes',
-  'defineCLICommands',
-])
-
-const hasHandlerProperty = (node: ts.Node): boolean => {
-  let found = false
-  const visit = (current: ts.Node) => {
-    if (found) return
-    if (
-      ts.isPropertyAssignment(current) &&
-      (ts.isIdentifier(current.name) || ts.isStringLiteral(current.name)) &&
-      (current.name.text === 'middleware' ||
-        current.name.text === 'permissions')
-    ) {
-      found = true
-      return
-    }
-    ts.forEachChild(current, visit)
-  }
-  visit(node)
-  return found
-}
-
-/**
- * Enforce addon authoring rules. Only runs when inspecting an addon package
- * (options.isAddon). Addons cannot wire transports, and their contracts cannot
- * carry middleware or permissions — those are the consuming app's concern.
- */
-export const checkAddonBans: AddWiring = (
-  logger,
-  node,
-  _checker,
-  _state,
-  options
-) => {
-  if (!options.isAddon) return
-  if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return
-
-  const name = node.expression.text
-
-  if (BANNED_WIRINGS.has(name)) {
-    logger.critical(
-      ErrorCode.ADDON_WIRING_NOT_ALLOWED,
-      `Addons must not call '${name}'. Declare contracts with define* and export functions; the consuming app wires them via refHTTP / refChannel / refCLI.`
-    )
-    return
-  }
-
-  if (CONTRACT_DEFINERS.has(name)) {
-    const [arg] = node.arguments
-    if (arg && hasHandlerProperty(arg)) {
-      logger.critical(
-        ErrorCode.ADDON_CONTRACT_HANDLERS_NOT_ALLOWED,
-        `Addon contract '${name}' must not declare middleware or permissions — these are applied by the consuming app, not the addon.`
-      )
-    }
-  }
-}

package/src/add/add-agent-scorer.test.ts

@@ -1,197 +0,0 @@
-import { strict as assert } from 'assert'
-import { describe, test } from 'node:test'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { inspect } from '../inspector.js'
-import { ErrorCode } from '../error-codes.js'
-import type { InspectorLogger } from '../types.js'
-
-const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
-  ({
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    diagnostic: ({ code, message }) => {
-      criticals.push({ code, message })
-    },
-    critical: (code: ErrorCode, message: string) => {
-      criticals.push({ code, message })
-    },
-    hasCriticalErrors: () => criticals.length > 0,
-  }) satisfies InspectorLogger
-
-const inspectSources = async (sources: Record<string, string>) => {
-  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-agent-scorer-'))
-  const files: Record<string, string> = {}
-  for (const [name, source] of Object.entries(sources)) {
-    files[name] = join(rootDir, name)
-    await writeFile(files[name]!, source)
-  }
-  const criticals: Array<{ code: ErrorCode; message: string }> = []
-  try {
-    const state = await inspect(makeLogger(criticals), Object.values(files), {
-      rootDir,
-    })
-    return { state, criticals }
-  } finally {
-    await rm(rootDir, { recursive: true, force: true })
-  }
-}
-
-const inspectSource = (source: string) =>
-  inspectSources({ 'grading.scorer.ts': source })
-
-describe('addAgentScorer', () => {
-  test('reads the lane off which constructor was called, not off a field', async () => {
-    const { state, criticals } = await inspectSource(
-      [
-        `export const brevity = pikkuAgentScorer({`,
-        `  name: 'brevity',`,
-        `  description: 'Shorter answers score higher',`,
-        `  score: () => ({ score: 1 }),`,
-        `})`,
-        `export const helpfulness = pikkuAgentJudge({`,
-        `  name: 'helpfulness',`,
-        `  description: 'Does the answer help',`,
-        `  model: 'claude-opus-5',`,
-        `  goal: 'Grade helpfulness.',`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.equal(state.scorers.scorersMeta['brevity']?.lane, 'fast')
-    assert.equal(state.scorers.scorersMeta['helpfulness']?.lane, 'slow')
-  })
-
-  test('defaults an unstated sample rate to grading every run', async () => {
-    const { state } = await inspectSource(
-      [
-        `export const brevity = pikkuAgentScorer({`,
-        `  name: 'brevity',`,
-        `  description: 'Shorter answers score higher',`,
-        `  score: () => ({ score: 1 }),`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.equal(state.scorers.scorersMeta['brevity']?.sampleRate, 1)
-    assert.equal(state.scorers.scorersMeta['brevity']?.requiresReference, false)
-  })
-
-  test('carries the sample rate and the reference requirement into the meta', async () => {
-    const { state } = await inspectSource(
-      [
-        `export const correctness = pikkuAgentJudge({`,
-        `  name: 'correctness',`,
-        `  description: 'Is the answer right',`,
-        `  model: 'claude-opus-5',`,
-        `  goal: 'Grade correctness.',`,
-        `  sampleRate: 0.1,`,
-        `  requiresReference: true,`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.equal(state.scorers.scorersMeta['correctness']?.sampleRate, 0.1)
-    assert.equal(
-      state.scorers.scorersMeta['correctness']?.requiresReference,
-      true
-    )
-  })
-
-  test('rejects a sample rate that is not a fraction', async () => {
-    const { state, criticals } = await inspectSource(
-      [
-        `export const brevity = pikkuAgentScorer({`,
-        `  name: 'brevity',`,
-        `  description: 'Shorter answers score higher',`,
-        `  sampleRate: 50,`,
-        `  score: () => ({ score: 1 }),`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.equal(criticals[0]?.code, ErrorCode.INVALID_VALUE)
-    assert.match(criticals[0]!.message, /between 0 and 1/)
-    assert.deepEqual(state.scorers.scorersMeta, {})
-  })
-
-  test('a scorer with no description is refused, since the meta is what names it', async () => {
-    const { criticals } = await inspectSource(
-      [
-        `export const brevity = pikkuAgentScorer({`,
-        `  name: 'brevity',`,
-        `  score: () => ({ score: 1 }),`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.equal(criticals[0]?.code, ErrorCode.MISSING_DESCRIPTION)
-  })
-
-  test('records where a scorer was declared, so codegen can import it back', async () => {
-    const { state } = await inspectSource(
-      [
-        `export const brevity = pikkuAgentScorer({`,
-        `  name: 'brevity',`,
-        `  description: 'Shorter answers score higher',`,
-        `  score: () => ({ score: 1 }),`,
-        `})`,
-      ].join('\n')
-    )
-
-    assert.equal(state.scorers.files.get('brevity')?.exportedName, 'brevity')
-    assert.match(
-      state.scorers.files.get('brevity')?.path ?? '',
-      /grading\.scorer\.ts$/
-    )
-  })
-})
-
-describe('an agent asking to be graded', () => {
-  const scorerFile = [
-    `export const brevity = pikkuAgentScorer({`,
-    `  name: 'brevity',`,
-    `  description: 'Shorter answers score higher',`,
-    `  score: () => ({ score: 1 }),`,
-    `})`,
-  ].join('\n')
-
-  const agent = (scorers: string) =>
-    [
-      `export const assistant = pikkuAgent({`,
-      `  name: 'assistant',`,
-      `  description: 'Answers questions',`,
-      `  goal: 'Answer the question.',`,
-      `  model: 'anthropic/claude-opus-5',`,
-      `  scorers: [${scorers}],`,
-      `})`,
-    ].join('\n')
-
-  test('carries the named scorers onto the agent meta', async () => {
-    const { state, criticals } = await inspectSources({
-      'grading.scorer.ts': scorerFile,
-      'assistant.agent.ts': agent(`'brevity'`),
-    })
-
-    assert.deepEqual(criticals, [])
-    assert.deepEqual(state.agents.agentsMeta['assistant']?.scorers, ['brevity'])
-  })
-
-  test('naming a scorer that does not exist fails the build rather than grading nothing', async () => {
-    const { criticals } = await inspectSources({
-      'grading.scorer.ts': scorerFile,
-      'assistant.agent.ts': agent(`'brevty'`),
-    })
-
-    const finding = criticals.find(
-      (critical) => critical.code === ErrorCode.AGENT_SCORER_NOT_FOUND
-    )
-    assert.ok(finding, `expected a scorer-not-found critical`)
-    assert.match(finding!.message, /brevty/)
-    assert.match(finding!.message, /Declared scorers: brevity/)
-  })
-})