@pikku/inspector 0.12.70 → 0.12.72

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 || {},