@pikku/inspector 0.12.69 → 0.12.72

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

@@ -2010,3 +2010,135 @@ describe('invokedFunctionsByFile serialization', () => {
     assert.strictEqual(restored.rpc.invokedFunctionsByFile.size, 0)
   })
 })
+
+describe('Workflow file pruning', () => {
+  const workflowState = () => {
+    const state = createMockInspectorState()
+    state.workflows.meta = {
+      moveOut: { pikkuFuncId: 'getUsers' } as any,
+      theMoveOutScenario: { pikkuFuncId: 'createUser' } as any,
+    }
+    state.workflows.graphMeta = {
+      moveOut: { pikkuFuncId: 'getUsers' } as any,
+      theMoveOutScenario: {
+        pikkuFuncId: 'createUser',
+        source: 'scenario',
+      } as any,
+    }
+    state.workflows.files = new Map([
+      [
+        'moveOut',
+        {
+          path: '/test/project/src/wirings/move-out.workflow.ts',
+          exportedName: 'moveOut',
+        },
+      ],
+      [
+        'theMoveOutScenario',
+        {
+          path: '/test/project/test/scenarios/the-move-out.scenario.ts',
+          exportedName: 'theMoveOutScenario',
+        },
+      ],
+    ])
+    return state
+  }
+
+  test('drops the file entry of a pruned workflow', () => {
+    const result = filterInspectorState(
+      workflowState(),
+      { names: ['getUsers'] },
+      mockLogger
+    )
+
+    assert.deepEqual(Object.keys(result.workflows.graphMeta), ['moveOut'])
+    assert.deepEqual([...result.workflows.files.keys()], ['moveOut'])
+  })
+
+  test('leaves the original state untouched', () => {
+    const state = workflowState()
+    filterInspectorState(state, { names: ['getUsers'] }, mockLogger)
+
+    assert.equal(state.workflows.files.size, 2)
+    assert.equal(Object.keys(state.workflows.graphMeta).length, 2)
+  })
+})
+
+describe('invokedAgentsByFile', () => {
+  test('round-trips through serialize/deserialize', () => {
+    const state = getInitialInspectorState('/test/project')
+    state.agents.invokedAgentsByFile = new Map([
+      ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+      [
+        '/test/project/src/api/tasks.ts',
+        new Set(['houseAssistant', 'gardenAssistant']),
+      ],
+    ])
+    const restored = deserializeInspectorState(
+      JSON.parse(JSON.stringify(serializeInspectorState(state as any)))
+    )
+    assert.ok(restored.agents.invokedAgentsByFile instanceof Map)
+    assert.strictEqual(restored.agents.invokedAgentsByFile.size, 2)
+    assert.deepStrictEqual(
+      [
+        ...restored.agents.invokedAgentsByFile.get(
+          '/test/project/src/api/tasks.ts'
+        )!,
+      ].sort(),
+      ['gardenAssistant', 'houseAssistant']
+    )
+  })
+
+  test('deserializing legacy state without the field yields an empty Map', () => {
+    const serialized = JSON.parse(
+      JSON.stringify(
+        serializeInspectorState(
+          getInitialInspectorState('/test/project') as any
+        )
+      )
+    )
+    delete serialized.agents.invokedAgentsByFile
+    const restored = deserializeInspectorState(serialized)
+    assert.ok(restored.agents.invokedAgentsByFile instanceof Map)
+    assert.strictEqual(restored.agents.invokedAgentsByFile.size, 0)
+  })
+
+  test('the filtered map is a clone, not the original', () => {
+    const state = createMockInspectorState()
+    state.agents = {
+      agentsMeta: {},
+      files: new Map(),
+      invokedAgentsByFile: new Map([
+        ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+      ]),
+    }
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    filtered.agents.invokedAgentsByFile.clear()
+    assert.strictEqual(state.agents.invokedAgentsByFile.size, 1)
+  })
+
+  test('keeps the entry of a kept function file and prunes the rest', () => {
+    const state = createMockInspectorState()
+    state.agents = {
+      agentsMeta: {},
+      files: new Map(),
+      invokedAgentsByFile: new Map([
+        ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+        ['/test/project/src/admin/settings.ts', new Set(['adminAssistant'])],
+      ]),
+    }
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.deepStrictEqual(
+      [...filtered.agents.invokedAgentsByFile.keys()],
+      ['/test/project/src/api/users.ts']
+    )
+  })
+})

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

@@ -21,6 +21,28 @@ type DeployFilter = {
   has(pikkuFuncId: string): boolean
 }
 
+/**
+ * Drop a workflow from every map that describes it. `files` and `graphFiles`
+ * are what the wiring generator iterates, and `graphMeta` is what tells a
+ * scenario apart from an app workflow — leaving a pruned workflow's file entry
+ * behind registers it anyway, and a scenario whose graphMeta has gone reads as
+ * an app workflow, which is how scenario steps reached deployed bundles.
+ */
+const pruneWorkflow = (
+  workflows: InspectorState['workflows'],
+  name: string,
+  pikkuFuncId: string | undefined
+) => {
+  delete workflows.graphMeta[name]
+  delete workflows.meta[name]
+  workflows.files.delete(name)
+  workflows.graphFiles.delete(name)
+  if (pikkuFuncId) {
+    workflows.files.delete(pikkuFuncId)
+    workflows.graphFiles.delete(pikkuFuncId)
+  }
+}
+
 // Module-level Set to track warned groups across multiple filter calls
 const globalWarnedGroups = new Set<string>()
 
@@ -449,6 +471,8 @@ export function filterInspectorState(
       ...state.workflows,
       graphMeta: JSON.parse(JSON.stringify(state.workflows?.graphMeta ?? {})),
       meta: JSON.parse(JSON.stringify(state.workflows?.meta ?? {})),
+      files: new Map(state.workflows?.files ?? []),
+      graphFiles: new Map(state.workflows?.graphFiles ?? []),
     },
     channels: {
       ...state.channels,
@@ -483,6 +507,15 @@ export function filterInspectorState(
       ...state.agents,
       agentsMeta: JSON.parse(JSON.stringify(state.agents?.agentsMeta ?? {})),
       files: new Map(),
+      invokedAgentsByFile: new Map(
+        [
+          ...(state.agents?.invokedAgentsByFile ??
+            new Map<string, Set<string>>()),
+        ].map(([file, agents]): [string, Set<string>] => [
+          file,
+          new Set(agents),
+        ])
+      ),
     },
     // Scorers carry through every filter. They are named by the agents that
     // survive it, and a deployment that quietly stopped grading would look
@@ -1098,12 +1131,10 @@ export function filterInspectorState(
         pikkuFuncId &&
         !filteredState.serviceAggregation.usedFunctions.has(pikkuFuncId)
       ) {
-        delete filteredState.workflows.graphMeta[name]
-        delete filteredState.workflows.meta[name]
+        pruneWorkflow(filteredState.workflows, name, pikkuFuncId)
       } else if (!pikkuFuncId) {
         // No function ID found — prune it
-        delete filteredState.workflows.graphMeta[name]
-        delete filteredState.workflows.meta[name]
+        pruneWorkflow(filteredState.workflows, name, pikkuFuncId)
       }
     }
 
@@ -1188,6 +1219,16 @@ export function filterInspectorState(
     filteredState.serviceAggregation.requiredServices.add('queueService')
   }
 
+  const keptFunctionFiles = new Set<string>()
+  for (const file of filteredState.functions.files.values()) {
+    if (file?.path) keptFunctionFiles.add(file.path)
+  }
+  for (const file of filteredState.agents.invokedAgentsByFile.keys()) {
+    if (!keptFunctionFiles.has(file)) {
+      filteredState.agents.invokedAgentsByFile.delete(file)
+    }
+  }
+
   if ((filteredState.rpc.wireAddonDeclarations?.size ?? 0) > 0) {
     const referencedIds = new Set<string>(
       filteredState.serviceAggregation.usedFunctions

package/src/utils/post-process.test.ts

@@ -13,6 +13,7 @@ import {
   validateAgentToolReferences,
   validateAgentModels,
   validateSchemaReferences,
+  proseOpensWithActor,
 } from './post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorState, InspectorLogger } from '../types.js'
@@ -1050,3 +1051,44 @@ describe('validateSchemaReferences', () => {
     assert.match(diagnostics[0]!.message, /2 function contracts name a schema/)
   })
 })
+
+describe('proseOpensWithActor', () => {
+  test('a quoted actor opening the prose doubles the subject', () => {
+    assert.equal(
+      proseOpensWithActor(`'sam' creates the browser-journey client`, 'sam'),
+      true
+    )
+  })
+
+  test('quotes and case are decoration, not the point', () => {
+    assert.equal(proseOpensWithActor('Sam creates the client', 'sam'), true)
+    assert.equal(proseOpensWithActor('sam creates the client', 'sam'), true)
+    assert.equal(proseOpensWithActor(`"sam" creates the client`, 'sam'), true)
+  })
+
+  test("an actor's own possessive is still the doubled subject", () => {
+    assert.equal(proseOpensWithActor("sam's client is created", 'sam'), true)
+  })
+
+  test('naming someone mid-sentence is ordinary prose', () => {
+    assert.equal(proseOpensWithActor('sends sam an invite', 'sam'), false)
+  })
+
+  // A persona keyed after a role noun must keep the word as a word: refusing
+  // "creates the admin client" for an actor called `admin` would make the
+  // check the reason to rename the persona.
+  test('an actor key that is also a common noun is only refused as the subject', () => {
+    assert.equal(
+      proseOpensWithActor('creates the admin client', 'admin'),
+      false
+    )
+    assert.equal(proseOpensWithActor('admin creates the client', 'admin'), true)
+  })
+
+  test('a longer name starting with the actor key is a different person', () => {
+    assert.equal(
+      proseOpensWithActor('samantha creates the client', 'sam'),
+      false
+    )
+  })
+})

package/src/utils/post-process.ts

@@ -22,6 +22,7 @@ import { relative } from 'node:path'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
 import { flattenScopeDefinitions } from '@pikku/core/scope'
 import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import type { ScenarioStepMeta } from '@pikku/core/scenario'
 import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js'
 
 /**
@@ -381,6 +382,35 @@ export function aggregateRequiredServices(
       requiredServices.add(service)
     }
   }
+
+  // 8. When this project IS an addon, what it needs from its parent is whatever
+  // its functions use minus whatever its own factory builds. Reading only the
+  // factory's second parameter missed everything the functions destructure and
+  // the factory never names — `kysely` above all — which left the contract empty
+  // and let a consumer omit it and fail at the first query instead of at build.
+  if (state.addonServicesFactorySeen) {
+    // Every function an addon declares is part of its published surface — a
+    // consumer calls it — so none of them are reachable from a local wiring and
+    // `usedFunctions` is empty. Aggregating only from wirings left the services
+    // map claiming an addon needs nothing, which is what drove addons to list
+    // their own services under `forceRequiredServices` by hand.
+    for (const funcMeta of Object.values(state.functions.meta)) {
+      addServices(funcMeta?.services)
+    }
+
+    const createdSet = new Set(state.addonCreatedServices ?? [])
+    const parentServices = new Set(parentDeclared)
+    for (const service of requiredServices) {
+      if (
+        !createdSet.has(service) &&
+        !internalServices.has(service) &&
+        !defaultServices.has(service)
+      ) {
+        parentServices.add(service)
+      }
+    }
+    state.addonRequiredParentServices = [...parentServices]
+  }
 }
 
 export function validateSecretOverrides(
@@ -911,6 +941,85 @@ export function validateScenarioServices(
   }
 }
 
+/**
+ * Does this step's prose open by naming the actor who is already its subject?
+ *
+ * `composeStepProse` renders the actor as the sentence's subject, so a step
+ * authored as `'sam' creates the client` reads "Given sam 'sam' creates the
+ * client". Only the subject position counts: a persona keyed after a role noun
+ * ("admin") must still be able to say "creates the admin client", and naming
+ * someone mid-sentence — "sends sam an invite" — is ordinary prose.
+ */
+export const proseOpensWithActor = (prose: string, actor: string): boolean => {
+  if (!actor) {
+    return false
+  }
+  const escaped = actor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^["'“‘\\s]*${escaped}(?:['’]s)?\\b`, 'i').test(prose)
+}
+
+/**
+ * The prose that will actually render for one step, in the runtime's own
+ * precedence: a call-site description overrides the step's template, which
+ * overrides its declared description, which falls back to the durable name.
+ *
+ * Every candidate is returned rather than only the winner, because a template
+ * is authored where the actor is not yet known — so it is wrong at every call
+ * site that runs it as the persona it names, not just the winning one.
+ */
+const renderableProse = (
+  step: ScenarioStepMeta,
+  stepMeta: { description?: string; scenarioStepTemplate?: string } | undefined
+): string[] => {
+  const description = step.options?.description
+  if (description) {
+    return [step.stepName, description]
+  }
+  return [
+    step.stepName,
+    stepMeta?.scenarioStepTemplate,
+    stepMeta?.description,
+  ].filter((prose): prose is string => typeof prose === 'string')
+}
+
+/**
+ * A step's prose must not open by naming the actor it already runs as (PKU681).
+ *
+ * The reporter renders the actor as the sentence's subject, so `'sam' creates
+ * the client` run as `actors.sam` reads "Given sam 'sam' creates the client" —
+ * and the hardcoded copy silently desyncs the moment the call site changes
+ * actor. Only the subject position is refused; naming someone mid-sentence is
+ * ordinary prose, and a persona keyed after a role noun can still say "creates
+ * the admin client".
+ */
+const validateStepProse = (
+  logger: InspectorLogger,
+  workflowName: string,
+  step: ScenarioStepMeta,
+  stepMeta: { description?: string; scenarioStepTemplate?: string } | undefined
+): void => {
+  const actor = step.actor
+  if (!actor) {
+    return
+  }
+  const offender = renderableProse(step, stepMeta).find((prose) =>
+    proseOpensWithActor(prose, actor)
+  )
+  if (offender === undefined) {
+    return
+  }
+  logger.critical(
+    ErrorCode.SCENARIO_STEP_PROSE_NAMES_ACTOR,
+    `Scenario '${workflowName}' names its actor in the step prose: '${offender}' runs as '${actor}'. ` +
+      `The reporter already renders the actor as the subject, so this reads ` +
+      `"${capitaliseFirst(step.phase)} ${actor} ${offender}". Drop the name and let ` +
+      `{ actor: actors.${actor} } supply it — the step reads as a bare third-person predicate.`
+  )
+}
+
+const capitaliseFirst = (value: string): string =>
+  value.charAt(0).toUpperCase() + value.slice(1)
+
 /**
  * Walk every scenario step, wherever it is nested, and validate the two things
  * that can only be known once both the workflow meta and the function meta
@@ -949,6 +1058,7 @@ export function validateScenarioSteps(
         }
         state.serviceAggregation.usedFunctions.add(step.stepFunc)
         const stepMeta = state.functions.meta[step.stepFunc]
+        validateStepProse(logger, workflowName, step, stepMeta)
         if (stepMeta?.scenarioStepRequiresActor && !step.actor) {
           const why = stepMeta.scenarioStepSurfaces?.includes('browser')
             ? 'declares a browser binding'

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

@@ -51,6 +51,8 @@ export interface SerializableInspectorState {
   >
   wireServicesMeta: Array<[string, string[]]>
   addonRequiredParentServices: string[]
+  addonCreatedServices: string[]
+  addonServicesFactorySeen: boolean
   addonServerlessIncompatible: Array<[string, string[]]>
   configFactories: Array<
     [
@@ -186,6 +188,7 @@ export interface SerializableInspectorState {
     files: string[]
   }
   agents: {
+    invokedAgentsByFile?: Array<[string, string[]]>
     agentsMeta: InspectorState['agents']['agentsMeta']
     files: [string, { path: string; exportedName: string }][]
   }
@@ -335,6 +338,8 @@ export function serializeInspectorState(
     wireServicesFactories: Array.from(state.wireServicesFactories.entries()),
     wireServicesMeta: Array.from(state.wireServicesMeta.entries()),
     addonRequiredParentServices: state.addonRequiredParentServices,
+    addonCreatedServices: state.addonCreatedServices,
+    addonServicesFactorySeen: state.addonServicesFactorySeen,
     addonServerlessIncompatible: Array.from(
       state.addonServerlessIncompatible.entries()
     ),
@@ -417,6 +422,11 @@ export function serializeInspectorState(
     agents: {
       agentsMeta: state.agents?.agentsMeta ?? {},
       files: Array.from(state.agents?.files?.entries() ?? []),
+      invokedAgentsByFile: Array.from(
+        (
+          state.agents?.invokedAgentsByFile ?? new Map<string, Set<string>>()
+        ).entries()
+      ).map(([file, agents]): [string, string[]] => [file, Array.from(agents)]),
     },
     scorers: {
       scorersMeta: state.scorers?.scorersMeta ?? {},
@@ -544,6 +554,8 @@ export function deserializeInspectorState(
     wireServicesFactories: new Map(data.wireServicesFactories),
     wireServicesMeta: new Map(data.wireServicesMeta),
     addonRequiredParentServices: data.addonRequiredParentServices || [],
+    addonCreatedServices: data.addonCreatedServices || [],
+    addonServicesFactorySeen: data.addonServicesFactorySeen ?? false,
     addonServerlessIncompatible: new Map(
       data.addonServerlessIncompatible || []
     ),
@@ -626,6 +638,11 @@ export function deserializeInspectorState(
     agents: {
       agentsMeta: data.agents?.agentsMeta || {},
       files: new Map(data.agents?.files || []),
+      invokedAgentsByFile: new Map(
+        (data.agents?.invokedAgentsByFile || []).map(
+          ([file, agents]): [string, Set<string>] => [file, new Set(agents)]
+        )
+      ),
     },
     scorers: {
       scorersMeta: data.scorers?.scorersMeta || {},