@pikku/inspector 0.12.47 → 0.12.49

package/src/add/add-feature.test.ts

@@ -0,0 +1,306 @@
+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 type { InspectorLogger } from '../types.js'
+
+function makeLogger(
+  criticals: Array<{ code: string; message: string }>
+): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }: any) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: any, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  } as InspectorLogger
+}
+
+const SCENARIOS = [
+  "import { pikkuScenario } from '@pikku/core/workflow'",
+  'export const lazyLoadScenario = pikkuScenario({',
+  "  title: 'A credential is loaded on first use',",
+  "  tags: ['credential'],",
+  '  func: async () => ({ ok: true }),',
+  '})',
+  'export const roundTripScenario = pikkuScenario({',
+  "  title: 'A credential round-trips',",
+  '  func: async (_services, _data: { name: string }) => ({ ok: true }),',
+  '})',
+].join('\n')
+
+async function run(featureSource: string) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-feature-'))
+  const scenarioFile = join(rootDir, 'credential.scenario.ts')
+  const featureFile = join(rootDir, 'credential.feature.ts')
+  await writeFile(scenarioFile, SCENARIOS)
+  await writeFile(featureFile, featureSource)
+  const criticals: Array<{ code: string; message: string }> = []
+  const state = await inspect(
+    makeLogger(criticals),
+    [scenarioFile, featureFile],
+    { rootDir }
+  )
+  return {
+    state,
+    criticals,
+    featureFile,
+    cleanup: () => rm(rootDir, { recursive: true, force: true }),
+  }
+}
+
+describe('addFeature', () => {
+  test('records where a feature is exported from', async () => {
+    const { state, criticals, featureFile, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        "  tags: ['credential'],",
+        '  scenarios: [lazyLoadScenario],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      assert.deepEqual(
+        [...state.workflows.featureFiles.entries()],
+        [
+          [
+            'credentialFeature',
+            {
+              path: featureFile,
+              exportedName: 'credentialFeature',
+              name: 'Credential API',
+              tags: ['credential'],
+              entries: [{ scenario: 'lazyLoadScenario' }],
+              unresolvedEntries: 0,
+              hasBefore: false,
+              hasAfter: false,
+            },
+          ],
+        ]
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('extracts the feature name, description and tags', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        "  description: 'How credentials are loaded and rotated',",
+        "  tags: ['credential', 'console'],",
+        '  scenarios: [lazyLoadScenario],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      const feature = state.workflows.featureFiles.get('credentialFeature')!
+      assert.equal(feature.name, 'Credential API')
+      assert.equal(
+        feature.description,
+        'How credentials are loaded and rotated'
+      )
+      assert.deepEqual(feature.tags, ['credential', 'console'])
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('resolves a literal scenarios array to scenario names, in order', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario, roundTripScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        '  scenarios: [roundTripScenario, lazyLoadScenario],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      const feature = state.workflows.featureFiles.get('credentialFeature')!
+      assert.deepEqual(feature.entries, [
+        { scenario: 'roundTripScenario' },
+        { scenario: 'lazyLoadScenario' },
+      ])
+      assert.equal(feature.unresolvedEntries, 0)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('resolves an aliased import back to the declared scenario name', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario as lazy } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        '  scenarios: [lazy],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      assert.deepEqual(
+        state.workflows.featureFiles.get('credentialFeature')!.entries,
+        [{ scenario: 'lazyLoadScenario' }]
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('resolves a { scenario, data } entry with its literal data', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { roundTripScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        '  scenarios: [',
+        "    { scenario: roundTripScenario, data: { name: 'stripe', retries: 2 } },",
+        "    { scenario: roundTripScenario, data: { name: 'google', retries: 0 } },",
+        '  ],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      assert.deepEqual(
+        state.workflows.featureFiles.get('credentialFeature')!.entries,
+        [
+          {
+            scenario: 'roundTripScenario',
+            data: { name: 'stripe', retries: 2 },
+          },
+          {
+            scenario: 'roundTripScenario',
+            data: { name: 'google', retries: 0 },
+          },
+        ]
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('records whether the feature has before/after hooks', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        '  before: async () => {},',
+        '  scenarios: [lazyLoadScenario],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      const feature = state.workflows.featureFiles.get('credentialFeature')!
+      assert.equal(feature.hasBefore, true)
+      assert.equal(feature.hasAfter, false)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a feature built by a loop keeps its literal entries and counts the rest', async () => {
+    // A spread of `.map()` cannot be enumerated statically — membership for it
+    // is resolved at runtime by object identity. Everything literal alongside it
+    // is still extracted, and the dynamic portion is counted rather than lost.
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario, roundTripScenario } from './credential.scenario.js'",
+        'export const credentialFeature = pikkuFeature({',
+        "  name: 'Credential API',",
+        '  scenarios: [',
+        '    lazyLoadScenario,',
+        "    ...['stripe', 'google'].map((name) => ({",
+        '      scenario: roundTripScenario,',
+        '      data: { name },',
+        '    })),',
+        '  ],',
+        '})',
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      const feature = state.workflows.featureFiles.get('credentialFeature')!
+      assert.deepEqual(feature.entries, [{ scenario: 'lazyLoadScenario' }])
+      assert.equal(feature.unresolvedEntries, 1)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('several features in one file are all recorded', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario, roundTripScenario } from './credential.scenario.js'",
+        "export const readFeature = pikkuFeature({ name: 'Read', scenarios: [lazyLoadScenario] })",
+        "export const writeFeature = pikkuFeature({ name: 'Write', scenarios: [roundTripScenario] })",
+      ].join('\n')
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      assert.deepEqual(
+        [...state.workflows.featureFiles.keys()],
+        ['readFeature', 'writeFeature']
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a feature that is not exported is a critical error', async () => {
+    const { state, criticals, cleanup } = await run(
+      [
+        "import { pikkuFeature } from '@pikku/core/workflow'",
+        "import { lazyLoadScenario } from './credential.scenario.js'",
+        "const credentialFeature = pikkuFeature({ name: 'Credential API', scenarios: [lazyLoadScenario] })",
+        'void credentialFeature',
+      ].join('\n')
+    )
+    try {
+      assert.equal(state.workflows.featureFiles.size, 0)
+      assert.equal(criticals.length, 1)
+      assert.match(criticals[0]!.message, /must be assigned to an export/)
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a project with no features records none', async () => {
+    const { state, criticals, cleanup } = await run(
+      "export const nothing = 'here'\n"
+    )
+    try {
+      assert.deepEqual(criticals, [])
+      assert.equal(state.workflows.featureFiles.size, 0)
+    } finally {
+      await cleanup()
+    }
+  })
+})

package/src/add/add-feature.ts

@@ -0,0 +1,253 @@
+import * as ts from 'typescript'
+import { extractFunctionName } from '../utils/extract-function-name.js'
+import { ErrorCode } from '../error-codes.js'
+import type {
+  AddWiring,
+  InspectorFeature,
+  InspectorFeatureEntry,
+} from '../types.js'
+
+/**
+ * Reads a fully literal expression into a plain value.
+ *
+ * Used for a `{ scenario, data }` entry's `data`, which is gherkin's
+ * `Examples:` row. Anything not literal yields `undefined` — a computed row
+ * belongs to the runtime-resolved portion, not to the extracted meta.
+ */
+const literalValue = (node: ts.Expression): unknown => {
+  if (ts.isStringLiteralLike(node)) {
+    return node.text
+  }
+  if (ts.isNumericLiteral(node)) {
+    return Number(node.text)
+  }
+  if (node.kind === ts.SyntaxKind.TrueKeyword) {
+    return true
+  }
+  if (node.kind === ts.SyntaxKind.FalseKeyword) {
+    return false
+  }
+  if (node.kind === ts.SyntaxKind.NullKeyword) {
+    return null
+  }
+  if (
+    ts.isPrefixUnaryExpression(node) &&
+    node.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(node.operand)
+  ) {
+    return -Number(node.operand.text)
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    const values: unknown[] = []
+    for (const element of node.elements) {
+      const value = literalValue(element)
+      if (value === undefined) {
+        return undefined
+      }
+      values.push(value)
+    }
+    return values
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    const value: Record<string, unknown> = {}
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        return undefined
+      }
+      const key =
+        ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)
+          ? property.name.text
+          : undefined
+      if (key === undefined) {
+        return undefined
+      }
+      const propertyValue = literalValue(property.initializer)
+      if (propertyValue === undefined) {
+        return undefined
+      }
+      value[key] = propertyValue
+    }
+    return value
+  }
+  return undefined
+}
+
+/**
+ * Resolves a scenario reference to the name it is declared under, following an
+ * import alias back to the original export so `{ x as y }` records `x`.
+ */
+const scenarioName = (
+  node: ts.Expression,
+  checker: ts.TypeChecker
+): string | undefined => {
+  if (!ts.isIdentifier(node)) {
+    return undefined
+  }
+  const symbol = checker.getSymbolAtLocation(node)
+  if (!symbol) {
+    return node.text
+  }
+  const resolved =
+    symbol.flags & ts.SymbolFlags.Alias
+      ? checker.getAliasedSymbol(symbol)
+      : symbol
+  return resolved.getName() || node.text
+}
+
+const getProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): ts.Expression | undefined => {
+  const property = config.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === name
+  )
+  return property && ts.isPropertyAssignment(property)
+    ? property.initializer
+    : undefined
+}
+
+const hasProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): boolean =>
+  config.properties.some(
+    (p) =>
+      (ts.isPropertyAssignment(p) ||
+        ts.isMethodDeclaration(p) ||
+        ts.isShorthandPropertyAssignment(p)) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === name
+  )
+
+const stringProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string | undefined => {
+  const value = getProperty(config, name)
+  return value && ts.isStringLiteralLike(value) ? value.text : undefined
+}
+
+const stringArrayProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string[] | undefined => {
+  const value = getProperty(config, name)
+  if (!value || !ts.isArrayLiteralExpression(value)) {
+    return undefined
+  }
+  const values = value.elements
+    .filter(ts.isStringLiteralLike)
+    .map((e) => e.text)
+  return values.length === value.elements.length ? values : undefined
+}
+
+const readEntry = (
+  element: ts.Expression,
+  checker: ts.TypeChecker
+): InspectorFeatureEntry | undefined => {
+  if (ts.isIdentifier(element)) {
+    const scenario = scenarioName(element, checker)
+    return scenario ? { scenario } : undefined
+  }
+
+  if (ts.isObjectLiteralExpression(element)) {
+    const reference = getProperty(element, 'scenario')
+    if (!reference) {
+      return undefined
+    }
+    const scenario = scenarioName(reference, checker)
+    if (!scenario) {
+      return undefined
+    }
+    const dataNode = getProperty(element, 'data')
+    if (!dataNode) {
+      return { scenario }
+    }
+    const data = literalValue(dataNode)
+    return data === undefined ? undefined : { scenario, data }
+  }
+
+  return undefined
+}
+
+/**
+ * Inspector for `pikkuFeature()` calls.
+ *
+ * A feature is the document structure the console renders — its name,
+ * description, tags and the order of its scenarios are what a reader sees — so
+ * everything the config states literally is extracted here.
+ *
+ * What cannot be extracted is a scenarios entry that is not literal:
+ * `...['stripe', 'google'].map((name) => ({ scenario, data: { name } }))` is
+ * ordinary TypeScript, and no AST walk can enumerate it. Those entries are
+ * counted in `unresolvedEntries` rather than dropped, and membership for them
+ * is resolved at runtime by object identity (`resolveFeatureScenarios`), where
+ * the array has actually been evaluated.
+ *
+ * The export location is recorded either way, which is what the CLI needs to
+ * emit its `addFeature(...)` wiring line.
+ */
+export const addFeature: AddWiring = (logger, node, checker, state) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'pikkuFeature') {
+    return
+  }
+
+  const { exportedName } = extractFunctionName(node, checker, state.rootDir)
+
+  if (!exportedName) {
+    logger.critical(
+      ErrorCode.MISSING_NAME,
+      `A pikkuFeature() must be assigned to an export — the export identifier is the feature's id.`
+    )
+    return
+  }
+
+  const feature: InspectorFeature = {
+    path: node.getSourceFile().fileName,
+    exportedName,
+    entries: [],
+    unresolvedEntries: 0,
+    hasBefore: false,
+    hasAfter: false,
+  }
+
+  const [config] = node.arguments
+  if (config && ts.isObjectLiteralExpression(config)) {
+    const name = stringProperty(config, 'name')
+    const description = stringProperty(config, 'description')
+    const tags = stringArrayProperty(config, 'tags')
+    if (name !== undefined) {
+      feature.name = name
+    }
+    if (description !== undefined) {
+      feature.description = description
+    }
+    if (tags !== undefined) {
+      feature.tags = tags
+    }
+    feature.hasBefore = hasProperty(config, 'before')
+    feature.hasAfter = hasProperty(config, 'after')
+
+    const scenarios = getProperty(config, 'scenarios')
+    if (scenarios && ts.isArrayLiteralExpression(scenarios)) {
+      for (const element of scenarios.elements) {
+        const entry = readEntry(element, checker)
+        if (entry) {
+          feature.entries.push(entry)
+        } else {
+          feature.unresolvedEntries += 1
+        }
+      }
+    }
+  }
+
+  state.workflows.featureFiles.set(exportedName, feature)
+}

package/src/add/add-functions.ts

@@ -21,6 +21,7 @@ import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import { findPiiPaths } from '../utils/check-pii-output.js'
+import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js'
 import type { NodeType } from '@pikku/core/node'
 
 const isValidVariableName = (name: string) => {
@@ -386,15 +387,27 @@ export const addFunctions: AddWiring = (
   }
 
   // Match identifiers that contain both "pikku" and "func" (case insensitive),
-  // plus pikkuScenario (a workflow wrapper without "func" in its name)
+  // plus pikkuScenario and pikkuScenarioStep (workflow wrappers without "func"
+  // in their names)
   const pikkuFuncPattern = /pikku.*func/i
   if (
     !pikkuFuncPattern.test(expression.text) &&
-    expression.text !== 'pikkuScenario'
+    expression.text !== 'pikkuScenario' &&
+    expression.text !== 'pikkuScenarioStep'
   ) {
     return
   }
 
+  // A scenario step is bundled like any invoked function, but is deliberately
+  // never RPC-registered: a step may drive a browser, so exposing it over the
+  // network would put a test harness on the public API surface.
+  const isScenarioStep = expression.text === 'pikkuScenarioStep'
+
+  // A scenario's own body. Marked so the codegen partitions and the deploy
+  // analyzer can tell it apart from an application workflow without having to
+  // reach into the workflow graph.
+  const isScenario = expression.text === 'pikkuScenario'
+
   // only handle calls like pikkuFunc(...)
   if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
     return
@@ -412,6 +425,17 @@ export const addFunctions: AddWiring = (
     return
   }
 
+  // pikku's own scenario instrumentation, which older projects still carry as a
+  // scaffolded file in their source. It is not application code and must not be
+  // registered, metadata'd or deployed as if it were — `pikku dev` registers the
+  // implementations itself, and that is the only server that should have them.
+  if (
+    isScenarioInstrumentationFunction(pikkuFuncId) ||
+    isScenarioInstrumentationFunction(name)
+  ) {
+    return
+  }
+
   let title: string | undefined
   let tags: string[] | undefined
   let summary: string | undefined
@@ -427,6 +451,8 @@ export const addFunctions: AddWiring = (
   let workflowQueued: boolean | undefined
   let workflowRetries: number | undefined
   let workflowTimeout: string | undefined
+  let scenarioStepBrowser: boolean | undefined
+  let scenarioStepTemplate: string | undefined
   let scopes: string[] | undefined
   let version: number | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
@@ -532,6 +558,12 @@ export const addFunctions: AddWiring = (
     workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout') as
       | string
       | undefined
+    scenarioStepBrowser = getPropertyValue(firstArg, 'browser') as
+      | boolean
+      | undefined
+    scenarioStepTemplate = getPropertyValue(firstArg, 'template') as
+      | string
+      | undefined
     scopes = getArrayPropertyValue(firstArg, 'scopes') ?? undefined
 
     // Extract approvalDescription identifier reference
@@ -1078,6 +1110,8 @@ export const addFunctions: AddWiring = (
     outputs: outputNames.filter((n) => n !== 'void') ?? null,
     expose: expose || undefined,
     remote: remote || undefined,
+    scenarioStep: isScenarioStep || undefined,
+    scenario: isScenario || undefined,
     mcp: mcpEnabled || undefined,
     readonly: readonly_ || undefined,
     deploy: deploy || undefined,
@@ -1086,6 +1120,8 @@ export const addFunctions: AddWiring = (
     workflowQueued: workflowQueued === true ? true : undefined,
     workflowRetries: workflowRetries ?? undefined,
     workflowTimeout: workflowTimeout ?? undefined,
+    scenarioStepBrowser: scenarioStepBrowser === true ? true : undefined,
+    scenarioStepTemplate: scenarioStepTemplate || undefined,
     scopes: scopes ?? undefined,
     implementationHash,
     version,
@@ -1182,7 +1218,7 @@ export const addFunctions: AddWiring = (
       return
     }
 
-    if (remote) {
+    if (remote && !isScenarioStep) {
       state.rpc.invokedFunctions.add(pikkuFuncId)
       // The consumer-facing surface a wireRemoteAddon imports (mirrors exposedMeta)
       state.rpc.remoteMeta[name] = pikkuFuncId
@@ -1192,7 +1228,7 @@ export const addFunctions: AddWiring = (
       })
     }
 
-    if (expose) {
+    if (expose && !isScenarioStep) {
       state.rpc.exposedMeta[name] = pikkuFuncId
       state.rpc.exposedFiles.set(name, {
         path: node.getSourceFile().fileName,
@@ -1202,12 +1238,14 @@ export const addFunctions: AddWiring = (
       state.serviceAggregation.usedFunctions.add(pikkuFuncId)
     }
 
-    // We add it to internal meta to allow autocomplete for everything
-    state.rpc.internalMeta[name] = pikkuFuncId
+    if (!isScenarioStep) {
+      // We add it to internal meta to allow autocomplete for everything
+      state.rpc.internalMeta[name] = pikkuFuncId
 
-    if (version !== undefined) {
-      state.rpc.internalMeta[pikkuFuncId] = pikkuFuncId
-      state.rpc.invokedFunctions.add(pikkuFuncId)
+      if (version !== undefined) {
+        state.rpc.internalMeta[pikkuFuncId] = pikkuFuncId
+        state.rpc.invokedFunctions.add(pikkuFuncId)
+      }
     }
 
     // But we only import the actual function if it's actually invoked to keep