@pikku/inspector 0.12.46 → 0.12.48

package/src/add/scenario-services.test.ts

@@ -0,0 +1,103 @@
+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 }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: any, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+}
+
+const stepFile = (dir: string) => join(dir, 'my.steps.ts')
+const stepSource = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const getTodos = pikkuSessionlessFunc({',
+  '  func: async ({ logger }) => [{ done: true }],',
+  '})',
+].join('\n')
+
+describe('scenarios may only destructure logger/config', () => {
+  test('a scenario destructuring a real service is a PKU673 critical', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-sc-svc-'))
+    const scenarioFile = join(rootDir, 'my.scenario.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      scenarioFile,
+      [
+        "import { pikkuScenario } from '@pikku/core/workflow'",
+        'declare const actors: Record<string, any>',
+        'export const badFlow = pikkuScenario(async ({ kysely }: any, _input, { workflow }) => {',
+        "  await workflow.do('Read todos', 'getTodos', {}, { actor: actors.pm })",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      await inspect(makeLogger(criticals), [stepFile(rootDir), scenarioFile], {
+        rootDir,
+      })
+      const pku673 = criticals.find((c) => c.code === 'PKU673')
+      assert.ok(
+        pku673,
+        `expected a PKU673 critical for a scenario destructuring 'kysely', got: ${JSON.stringify(criticals)}`
+      )
+      assert.ok(
+        pku673.message.includes('kysely'),
+        `PKU673 should name the offending service, got: ${pku673.message}`
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a scenario destructuring only logger is allowed', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-sc-ok-'))
+    const scenarioFile = join(rootDir, 'my.scenario.ts')
+    await writeFile(stepFile(rootDir), stepSource)
+    await writeFile(
+      scenarioFile,
+      [
+        "import { pikkuScenario } from '@pikku/core/workflow'",
+        'declare const actors: Record<string, any>',
+        'export const goodFlow = pikkuScenario(async ({ logger }, _input, { workflow }) => {',
+        "  await workflow.do('Read todos', 'getTodos', {}, { actor: actors.pm })",
+        '  return { ok: true }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(
+        makeLogger(criticals),
+        [stepFile(rootDir), scenarioFile],
+        { rootDir }
+      )
+      assert.ok(
+        !criticals.some((c) => c.code === 'PKU673'),
+        `logger is allowed in a scenario; got: ${JSON.stringify(criticals)}`
+      )
+      assert.equal((state.workflows.meta as any).goodFlow?.scenario, true)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/scenario-skip.test.ts

@@ -0,0 +1,83 @@
+/**
+ * A scenario can declare why it is held out of a default run. The reason has to
+ * reach the meta, because the runner reports skips from there — if it were
+ * dropped in extraction the scenario would silently run anyway, which is the
+ * opposite of what the author asked for.
+ */
+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'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  diagnostic: () => {},
+  critical: () => {},
+  hasCriticalErrors: () => false,
+} as unknown as InspectorLogger
+
+const STEPS = [
+  "import { pikkuScenarioStep } from '@pikku/core'",
+  'export const buysAnApple = pikkuScenarioStep({',
+  "  name: 'buysAnApple',",
+  "  description: 'buys an apple',",
+  '  func: async ({ logger }, data: { qty: number }) => ({ ok: data.qty > 0 }),',
+  '})',
+].join('\n')
+
+const scenarioSource = (properties: string[]) =>
+  [
+    "import { pikkuScenario } from '@pikku/core/workflow'",
+    'export const shopFlow = pikkuScenario({',
+    ...properties.map((line) => `  ${line}`),
+    '  func: async (_services, _input, { scenario }: any) => {',
+    "    await scenario.when('buys an apple', 'buysAnApple', { qty: 1 })",
+    '    return { ok: true }',
+    '  },',
+    '})',
+  ].join('\n')
+
+async function inspectScenario(properties: string[]) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-scenario-skip-'))
+  const stepsFile = join(rootDir, 'shop.steps.ts')
+  const scenarioFile = join(rootDir, 'shop.scenario.ts')
+  await writeFile(stepsFile, STEPS)
+  await writeFile(scenarioFile, scenarioSource(properties))
+  const state = await inspect(logger, [stepsFile, scenarioFile], { rootDir })
+  return {
+    meta: state.workflows.meta['shopFlow'] as any,
+    cleanup: () => rm(rootDir, { recursive: true, force: true }),
+  }
+}
+
+describe('scenario skip', () => {
+  test('a declared skip reason reaches the meta', async () => {
+    const { meta, cleanup } = await inspectScenario([
+      "title: 'Installs an addon',",
+      "skip: 'mutates the project — needs a fresh server',",
+    ])
+    try {
+      assert.equal(meta.skip, 'mutates the project — needs a fresh server')
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a scenario that declares none carries none', async () => {
+    const { meta, cleanup } = await inspectScenario([
+      "title: 'Installs an addon',",
+    ])
+    try {
+      assert.equal(meta.skip, undefined)
+      assert.equal(meta.scenario, true)
+    } finally {
+      await cleanup()
+    }
+  })
+})

package/src/error-codes.ts

@@ -22,6 +22,9 @@ export enum ErrorCode {
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
   SCENARIO_HAS_SERVICES = 'PKU673',
   EXPECT_EVENTUALLY_SCENARIO_ONLY = 'PKU675',
+  SCENARIO_BROWSER_STEP_NEEDS_ACTOR = 'PKU677',
+  SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
+  SCENARIO_NOT_EXTRACTABLE = 'PKU679',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
   WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',

package/src/index.ts

@@ -27,6 +27,7 @@ export type {
   VersionManifest,
   VersionManifestEntry,
 } from './utils/contract-hashes.js'
+export type { InspectorFeature, InspectorFeatureEntry } from './types.js'
 export { serializeMCPJson } from './utils/serialize-mcp-json.js'
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js'
 export {

package/src/inspector.ts

@@ -1,6 +1,6 @@
 import * as ts from 'typescript'
 import { performance } from 'perf_hooks'
-import { resolve } from 'path'
+import { dirname, resolve } from 'path'
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 import type {
@@ -27,6 +27,8 @@ import {
   computeRequiredSchemas,
   computeDiagnostics,
   validateSchemaWiringSeparation,
+  validateScenarioServices,
+  validateScenarioSteps,
   validateWorkflowGraphAddons,
 } from './utils/post-process.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
@@ -121,6 +123,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       files: new Map(),
       graphMeta: {},
       graphFiles: new Map(),
+      featureFiles: new Map(),
       invokedWorkflows: new Set(),
     },
     rpc: {
@@ -240,6 +243,49 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
   }
 }
 
+/**
+ * The path mappings the inspector's program has to share with the project.
+ *
+ * The inspector builds its own program rather than reusing the project's, which
+ * is what keeps a cold run affordable — but a project that reaches its generated
+ * code through a tsconfig `paths` entry resolves that import through those
+ * mappings and nothing else. Without them the factory an inspected function is
+ * passed to resolves to `any`, so a function whose input type comes from the
+ * factory's contextual type (rather than an explicit generic or a named schema)
+ * silently records no input at all.
+ *
+ * Only resolution keys are copied. Type-inference options such as `strict` stay
+ * the inspector's own, because changing those would change the recorded types.
+ */
+const readProjectPathMappings = (
+  logger: InspectorLogger,
+  tsconfig: string | undefined
+): ts.CompilerOptions => {
+  if (!tsconfig) {
+    return {}
+  }
+  const configPath = resolve(tsconfig)
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile)
+  if (configFile.error || !configFile.config) {
+    logger.debug(
+      `Could not read ${configPath} for path mappings; imports that rely on them will not resolve`
+    )
+    return {}
+  }
+  const { options: projectOptions } = ts.parseJsonConfigFileContent(
+    configFile.config,
+    ts.sys,
+    dirname(configPath)
+  )
+  const { baseUrl, paths, rootDirs, pathsBasePath } = projectOptions
+  return {
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
+    ...(paths !== undefined ? { paths } : {}),
+    ...(rootDirs !== undefined ? { rootDirs } : {}),
+    ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
+  }
+}
+
 export const inspect = async (
   logger: InspectorLogger,
   routeFiles: string[],
@@ -247,6 +293,7 @@ export const inspect = async (
 ): Promise<InspectorState> => {
   const normalizedRouteFiles = routeFiles.map((file) => resolve(file))
   const compilerOptions: ts.CompilerOptions = {
+    ...readProjectPathMappings(logger, options.tsconfig),
     target: ts.ScriptTarget.ESNext,
     module: ts.ModuleKind.Node16,
     skipLibCheck: true,
@@ -407,6 +454,8 @@ export const inspect = async (
     computeDiagnostics(state)
     validateSchemaWiringSeparation(logger, state)
     validateWorkflowGraphAddons(logger, state)
+    validateScenarioServices(logger, state)
+    validateScenarioSteps(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(

package/src/tsconfig-paths.test.ts

@@ -0,0 +1,90 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdir, 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'
+
+const logger: InspectorLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  diagnostic: () => {},
+  critical: () => {},
+  hasCriticalErrors: () => false,
+}
+
+const FACTORY = [
+  'export type Config = {',
+  '  name: string',
+  '  func: (services: any, data: { qty: number }) => Promise<{ ok: boolean }>',
+  '}',
+  'export const pikkuSessionlessFunc = (config: Config): Config => config',
+].join('\n')
+
+// The parameter is deliberately unannotated: its type can only come from the
+// factory's contextual type, which is exactly what an unresolved import loses.
+const funcSource = (specifier: string) =>
+  [
+    `import { pikkuSessionlessFunc } from '${specifier}'`,
+    'export const buysAnApple = pikkuSessionlessFunc({',
+    "  name: 'buysAnApple',",
+    '  func: async (_services, data) => ({ ok: data.qty > 0 }),',
+    '})',
+  ].join('\n')
+
+const makeProject = async (specifier: string) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-tsconfig-paths-'))
+  await mkdir(join(rootDir, 'generated'))
+  await mkdir(join(rootDir, 'src'))
+  await writeFile(
+    join(rootDir, 'tsconfig.json'),
+    JSON.stringify({
+      compilerOptions: {
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        paths: { '#gen/*': ['./generated/*'] },
+      },
+    })
+  )
+  await writeFile(
+    join(rootDir, 'package.json'),
+    JSON.stringify({ type: 'module' })
+  )
+  await writeFile(join(rootDir, 'generated', 'factory.ts'), FACTORY)
+  const funcFile = join(rootDir, 'src', 'apple.func.ts')
+  await writeFile(funcFile, funcSource(specifier))
+  return { rootDir, funcFile, tsconfig: join(rootDir, 'tsconfig.json') }
+}
+
+describe('tsconfig path mappings', () => {
+  test('a relative import gives the function its input type', async () => {
+    const { rootDir, funcFile } = await makeProject('../generated/factory.js')
+    try {
+      const state = await inspect(logger, [funcFile], { rootDir })
+      const meta = state.functions.meta['buysAnApple']
+      assert.ok(meta, 'buysAnApple meta should exist')
+      assert.deepStrictEqual(meta!.inputs, ['BuysAnAppleInput'])
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('an import that only resolves through tsconfig paths keeps its input type', async () => {
+    const { rootDir, funcFile, tsconfig } = await makeProject('#gen/factory.js')
+    try {
+      const state = await inspect(logger, [funcFile], { rootDir, tsconfig })
+      const meta = state.functions.meta['buysAnApple']
+      assert.ok(meta, 'buysAnApple meta should exist')
+      assert.deepStrictEqual(
+        meta!.inputs,
+        ['BuysAnAppleInput'],
+        'without the project path mappings the factory resolves to `any`, and the input is silently dropped'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/types.ts

@@ -273,6 +273,12 @@ export type InspectorOptions = Partial<{
   rootDir: string
   isAddon: boolean
   sourceFile: ts.SourceFile
+  /**
+   * The project's tsconfig, read for its path mappings only. The inspector's
+   * program needs them to resolve imports the project reaches through `paths`;
+   * unlike `schemaConfig.tsconfig` this is also needed on a setup-only run.
+   */
+  tsconfig: string
   types: Partial<{
     configFileType: string
     userSessionType: string
@@ -423,6 +429,36 @@ export interface AuthDefinition {
   services: FunctionServicesMeta
 }
 
+/** One statically resolved entry of a feature's `scenarios` array. */
+export interface InspectorFeatureEntry {
+  /** The scenario's declared export name, with any import alias followed back. */
+  scenario: string
+  /** A `{ scenario, data }` entry's literal data — gherkin's `Examples:`. */
+  data?: unknown
+}
+
+/** A `pikkuFeature` export, as far as it can be read from the source. */
+export interface InspectorFeature {
+  path: string
+  exportedName: string
+  name?: string
+  description?: string
+  tags?: string[]
+  entries: InspectorFeatureEntry[]
+  /**
+   * Entries that are not literal — a spread, a `.map()`, a call. Counted rather
+   * than dropped so the console can say the listing is partial instead of
+   * quietly showing a short feature.
+   */
+  unresolvedEntries: number
+  /**
+   * Feature hooks run once around the whole group, never per scenario, and are
+   * runtime-only — so only their presence is recorded.
+   */
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
 export interface InspectorState {
   rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
@@ -466,6 +502,15 @@ export interface InspectorState {
     files: Map<string, { path: string; exportedName: string }>
     graphMeta: SerializedWorkflowGraphs
     graphFiles: Map<string, { path: string; exportedName: string }>
+    /**
+     * `pikkuFeature` exports, keyed by export identifier.
+     *
+     * Everything the config states literally is extracted here, because a
+     * feature is the document structure the console renders. Entries built by
+     * an ordinary loop cannot be enumerated statically — those are counted in
+     * `unresolvedEntries` and resolved at runtime by object identity instead.
+     */
+    featureFiles: Map<string, InspectorFeature>
     invokedWorkflows: Set<string>
   }
   rpc: {

package/src/utils/extract-function-name.ts

@@ -45,6 +45,40 @@ export function funcIdToTypeName(id: string): string {
     .join('')
 }
 
+/**
+ * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
+ * scenarios reference a step by that string, so it must become the pikkuFuncId
+ * (and hence the generated step map's key), not just a cosmetic label the way
+ * `pikkuMiddleware`/`pikkuAgent` use it.
+ */
+function extractScenarioStepName(
+  callExpr: ts.Node,
+  result: ExtractedFunctionName
+): void {
+  if (
+    !ts.isCallExpression(callExpr) ||
+    !ts.isIdentifier(callExpr.expression) ||
+    callExpr.expression.text !== 'pikkuScenarioStep'
+  ) {
+    return
+  }
+  const firstArg = callExpr.arguments[0]
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) {
+    return
+  }
+  for (const prop of firstArg.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === 'name' &&
+      ts.isStringLiteral(prop.initializer)
+    ) {
+      result.explicitName = prop.initializer.text
+      return
+    }
+  }
+}
+
 export function extractFunctionName(
   callExpr: ts.Node,
   checker: ts.TypeChecker,
@@ -63,6 +97,8 @@ export function extractFunctionName(
     version: null,
   }
 
+  extractScenarioStepName(callExpr, result)
+
   const workflowHelpers = new Set([
     'workflow',
     'workflowStart',

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

@@ -63,6 +63,7 @@ function makeState(
     functionsMeta?: Record<string, any>
     addonFunctions?: Record<string, Record<string, any>>
     addonRequiredParentServices?: string[]
+    authServices?: string[]
   } = {}
 ): Omit<InspectorState, 'typesLookup'> {
   return {
@@ -99,6 +100,13 @@ function makeState(
     rpc: { internalMeta: {}, exposedMeta: {} },
     addonFunctions: overrides.addonFunctions ?? {},
     addonRequiredParentServices: overrides.addonRequiredParentServices ?? [],
+    auth: overrides.authServices
+      ? {
+          definition: {
+            services: { optimized: true, services: overrides.authServices },
+          },
+        }
+      : {},
   } as unknown as Omit<InspectorState, 'typesLookup'>
 }
 
@@ -306,6 +314,26 @@ describe('aggregateRequiredServices — per-function addon services', () => {
   })
 })
 
+describe('aggregateRequiredServices — the auth factory’s own services', () => {
+  test('an auth definition contributes its services before its handler exists', () => {
+    // The state a clean checkout produces: the project declares
+    // `pikkuBetterAuth`, so the definition is inspected, but the handler the CLI
+    // generates from it has not been written yet — so nothing in functions.meta
+    // mentions the services `authorize` reads.
+    const state = makeState({ authServices: ['kysely', 'jwt'] })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('kysely'))
+    assert.ok(required.has('jwt'))
+  })
+
+  test('a project without auth is unaffected', () => {
+    const state = makeState()
+    aggregateRequiredServices(state)
+    assert.equal(state.serviceAggregation.requiredServices.size, 0)
+  })
+})
+
 describe('override validation resolves the override target (value), not the logical key', () => {
   test('validateSecretOverrides accepts an override whose value is a declared secret', () => {
     const { logger, criticals } = makeCriticalLogger()
@@ -422,7 +450,10 @@ describe('validateRemoteAddonDependencies (wireRemoteAddon must be a devDependen
         })
       )
       assert.equal(criticals.length, 1)
-      assert.equal(criticals[0]!.code, ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY)
+      assert.equal(
+        criticals[0]!.code,
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY
+      )
       assert.match(criticals[0]!.message, /devDependencies/)
     } finally {
       rmSync(dir, { recursive: true, force: true })
@@ -441,7 +472,10 @@ describe('validateRemoteAddonDependencies (wireRemoteAddon must be a devDependen
         })
       )
       assert.equal(criticals.length, 1)
-      assert.equal(criticals[0]!.code, ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY)
+      assert.equal(
+        criticals[0]!.code,
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY
+      )
     } finally {
       rmSync(dir, { recursive: true, force: true })
     }