@pikku/inspector 0.12.49 → 0.12.52

package/src/add/add-personas.ts

@@ -0,0 +1,276 @@
+import * as ts from 'typescript'
+import { DISPOSITIONS } from '@pikku/core/virtual-user'
+import { isRunnablePersona } from '@pikku/core/persona'
+import type {
+  PersonaAccountMeta,
+  PersonaMeta,
+} from '@pikku/core/persona'
+import { ErrorCode } from '../error-codes.js'
+import type { AddWiring, InspectorLogger } from '../types.js'
+import {
+  booleanProperty,
+  getProperty,
+  numberProperty,
+  stringArrayProperty,
+  stringProperty,
+  unwrapAs,
+} from '../utils/literal-properties.js'
+
+type Tuning = NonNullable<PersonaMeta['tuning']>
+
+/** A dial and the range outside which it is a mistake rather than a choice. */
+const RATES: [keyof Tuning, number, number][] = [
+  ['temperature', 0, 2],
+  ['repeatRate', 0, 1],
+  ['reReadRate', 0, 1],
+]
+
+/**
+ * `{ moves, temperature, repeatRate, … }` — a disposition's dials, overridden.
+ *
+ * The ranges are checked here rather than at run time because these are the
+ * kind of typo that does not throw: `repeatRate: 18` meaning 18% would silently
+ * double every call the persona makes, and you would read the run as a product
+ * bug.
+ */
+const tuningProperty = (
+  config: ts.ObjectLiteralExpression,
+  onError: (message: string) => void
+): Tuning | undefined => {
+  const value = getProperty(config, 'tuning')
+  if (!value || !ts.isObjectLiteralExpression(value)) {
+    return undefined
+  }
+
+  const tuning: Tuning = {}
+
+  const movesValue = getProperty(value, 'moves')
+  if (movesValue && ts.isObjectLiteralExpression(movesValue)) {
+    const moves: NonNullable<Tuning['moves']> = {}
+    for (const move of ['continue', 'suspend', 'resume', 'abandon'] as const) {
+      const weight = numberProperty(movesValue, move)
+      if (weight === undefined) {
+        continue
+      }
+      if (weight < 0) {
+        onError(`tuning.moves.${move} must not be negative (got ${weight}).`)
+        continue
+      }
+      moves[move] = weight
+    }
+    if (Object.keys(moves).length) {
+      tuning.moves = moves
+    }
+  }
+
+  for (const [name, min, max] of RATES) {
+    const rate = numberProperty(value, name)
+    if (rate === undefined) {
+      continue
+    }
+    if (rate < min || rate > max) {
+      onError(`tuning.${name} must be between ${min} and ${max} (got ${rate}).`)
+      continue
+    }
+    Object.assign(tuning, { [name]: rate })
+  }
+
+  for (const flag of ['emptyMemory', 'readOnly', 'invertedOracle'] as const) {
+    const declared = booleanProperty(value, flag)
+    if (declared !== undefined) {
+      tuning[flag] = declared
+    }
+  }
+
+  const instructions = stringProperty(value, 'instructions')
+  if (instructions !== undefined) {
+    tuning.instructions = instructions
+  }
+
+  return Object.keys(tuning).length ? tuning : undefined
+}
+
+const accountProperty = (
+  value: ts.Expression | undefined
+): PersonaAccountMeta | undefined => {
+  if (!value || !ts.isObjectLiteralExpression(value)) {
+    return undefined
+  }
+  const provider = stringProperty(value, 'provider')
+  return provider === undefined ? {} : { provider }
+}
+
+const linkedAccountsProperty = (
+  config: ts.ObjectLiteralExpression,
+  personaId: string,
+  logger: InspectorLogger
+): Record<string, PersonaAccountMeta> | undefined => {
+  const value = getProperty(config, 'linkedAccounts')
+  if (!value || !ts.isObjectLiteralExpression(value)) {
+    return undefined
+  }
+
+  const accounts: Record<string, PersonaAccountMeta> = {}
+  for (const prop of value.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+    if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        `Persona '${personaId}' has a linked account whose key is not a literal.`
+      )
+      continue
+    }
+    const account = accountProperty(prop.initializer)
+    if (!account) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Persona '${personaId}' linked account '${prop.name.text}' must be an object literal.`
+      )
+      continue
+    }
+    accounts[prop.name.text] = account
+  }
+
+  return Object.keys(accounts).length ? accounts : undefined
+}
+
+/**
+ * Inspector for `definePersonas()` calls.
+ *
+ * A persona is entirely declaration — a person, their roles, what they want —
+ * so there is no code body and nothing to resolve at runtime. What is read here
+ * is the whole thing, and it is generated straight to `personas.gen.json` for
+ * the CLI and the console to read without loading the app.
+ *
+ * `name` is the one field that cannot be defaulted. A persona without one is
+ * not a person, and the console has nothing to show.
+ */
+export const addPersonas: AddWiring = (logger, node, _checker, state) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'definePersonas') {
+    return
+  }
+
+  const firstArg = node.arguments[0]
+  if (!firstArg) {
+    return
+  }
+
+  const unwrapped = unwrapAs(firstArg)
+  if (!ts.isObjectLiteralExpression(unwrapped)) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      'definePersonas() needs an inline object — personas are read statically, never evaluated.'
+    )
+    return
+  }
+
+  const sourceFile = node.getSourceFile().fileName
+  const known = Object.keys(DISPOSITIONS)
+
+  for (const prop of unwrapped.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+
+    if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        'A persona is declared with a key that is not a literal.'
+      )
+      continue
+    }
+    const id = prop.name.text
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Persona '${id}' must be an object literal.`
+      )
+      continue
+    }
+    const config = prop.initializer
+
+    const name = stringProperty(config, 'name')
+    if (!name) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Persona '${id}' needs a literal 'name' — a persona is a person, and the console has nothing to show without one.`
+      )
+      continue
+    }
+
+    // The generated `definePersonas` types this as a union, so a bad value only
+    // reaches here in source that does not compile. Caught anyway: a
+    // disposition is the entire behaviour, and defaulting a typo to `realistic`
+    // would run a different person than the one that was written.
+    const disposition = stringProperty(config, 'disposition')
+    if (disposition !== undefined && !known.includes(disposition)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Persona '${id}' has an unknown disposition '${disposition}'. One of: ${known.join(', ')}`
+      )
+      continue
+    }
+
+    let tuningFailed = false
+    const tuning = tuningProperty(config, (message) => {
+      tuningFailed = true
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Persona '${id}': ${message}`
+      )
+    })
+    if (tuningFailed) {
+      continue
+    }
+
+    const account = accountProperty(getProperty(config, 'account'))
+    const declaredRunnable = booleanProperty(config, 'runnable')
+
+    const persona: PersonaMeta = {
+      id,
+      name,
+      roles: stringArrayProperty(config, 'roles') ?? [],
+      goals: stringArrayProperty(config, 'goals') ?? [],
+      tags: stringArrayProperty(config, 'tags') ?? [],
+      runnable: isRunnablePersona({
+        ...(declaredRunnable !== undefined
+          ? { runnable: declaredRunnable }
+          : {}),
+        ...(account ? { account } : {}),
+      }),
+      sourceFile,
+    }
+
+    const jobTitle = stringProperty(config, 'jobTitle')
+    if (jobTitle !== undefined) persona.jobTitle = jobTitle
+    const description = stringProperty(config, 'description')
+    if (description !== undefined) persona.description = description
+    const personality = stringProperty(config, 'personality')
+    if (personality !== undefined) persona.personality = personality
+    if (disposition !== undefined) {
+      persona.disposition = disposition as PersonaMeta['disposition']
+    }
+    if (tuning !== undefined) persona.tuning = tuning
+    const fixtures = stringArrayProperty(config, 'fixtures')
+    if (fixtures !== undefined) persona.fixtures = fixtures
+    // Left absent rather than resolved here: "everywhere but production" is a
+    // fact about the config, and the inspector has no business baking today's
+    // environment list into a meta file that outlives it.
+    const environments = stringArrayProperty(config, 'environments')
+    if (environments !== undefined) persona.environments = environments
+    if (account !== undefined) persona.account = account
+    const linkedAccounts = linkedAccountsProperty(config, id, logger)
+    if (linkedAccounts !== undefined) persona.linkedAccounts = linkedAccounts
+
+    state.personas.files.add(sourceFile)
+    state.personas.definitions.push(persona)
+  }
+}

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

@@ -30,13 +30,13 @@ const STEPS = [
   'export const buysAnApple = pikkuScenarioStep({',
   "  name: 'buysAnApple',",
   "  description: 'buys an apple',",
-  '  browser: true,',
-  '  func: async ({ logger }, data: { qty: number }) => ({ ok: data.qty > 0 }),',
+  '  browser: async ({ logger }, data: { qty: number }) => ({ ok: data.qty > 0 }),',
+  '  default: async ({ logger }, data: { qty: number }) => ({ ok: data.qty > 0 }),',
   '})',
   'export const seesAReceipt = pikkuScenarioStep({',
   "  name: 'seesAReceipt',",
   "  description: 'sees a receipt',",
-  '  func: async ({ logger }) => ({ ok: true }),',
+  '  default: async ({ logger }) => ({ ok: true }),',
   '})',
 ].join('\n')
 
@@ -209,6 +209,52 @@ describe('pikkuScenarioStep', () => {
     }
   })
 
+  test('a scenario that never asserts is a PKU680 critical', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.when('buys an apple', 'buysAnApple', { qty: 2 }, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU680'),
+        `a flow with no 'then' proves only that nothing threw, and contributes 0/0 to witness coverage, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a scenario with an assertion is not flagged', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU680').length,
+        0,
+        `got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a scenario driving only rpc steps is not flagged — it has no step ladder to assert on', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.do('reads the order', 'orderGet', { orderId: 'o1' })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU680').length,
+        0,
+        `the rule is about scenarios written as given/when/then, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
   test('a non-browser step without an actor is allowed', async () => {
     const { criticals, cleanup } = await run([
       "await scenario.given('sees a receipt', 'seesAReceipt', {})",

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

@@ -39,8 +39,8 @@ describe('addScope inspector', () => {
   test('extracts a flat scope', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({',
         '  admin: {',
         "    displayName: 'Administration',",
         "    description: 'Administrative access',",
@@ -62,8 +62,8 @@ describe('addScope inspector', () => {
   test('extracts a displayName at every depth', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({',
         '  admin: {',
         "    displayName: 'Administration',",
         '    scopes: {',
@@ -90,8 +90,8 @@ describe('addScope inspector', () => {
   test('extracts a nested scope tree', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({',
         '  admin: {',
         '    scopes: {',
         '      invoices: {',
@@ -120,8 +120,8 @@ describe('addScope inspector', () => {
   test('records the source file', async () => {
     const { state, file } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({ admin: {} })',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ admin: {} })',
       ].join('\n')
     )
 
@@ -134,8 +134,8 @@ describe('addScope inspector', () => {
   test('extracts several roots from one declaration', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({ admin: {}, billing: { scopes: { read: {} } } })',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ admin: {}, billing: { scopes: { read: {} } } })',
       ].join('\n')
     )
 
@@ -150,9 +150,9 @@ describe('addScope inspector', () => {
   test('extracts several declarations', async () => {
     const { state } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        'wireScope({ admin: {} })',
-        'wireScope({ billing: {} })',
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ admin: {} })',
+        'defineScope({ billing: {} })',
       ].join('\n')
     )
 
@@ -165,8 +165,8 @@ describe('addScope inspector', () => {
   test('is critical when a root embeds the separator', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        "wireScope({ 'admin:users': {} })",
+        "import { defineScope } from '@pikku/core/scope'",
+        "defineScope({ 'admin:users': {} })",
       ].join('\n')
     )
 
@@ -179,8 +179,8 @@ describe('addScope inspector', () => {
   test('is critical when a root is the wildcard', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        "wireScope({ '*': {} })",
+        "import { defineScope } from '@pikku/core/scope'",
+        "defineScope({ '*': {} })",
       ].join('\n')
     )
 
@@ -193,9 +193,9 @@ describe('addScope inspector', () => {
   test('is critical when a root key is not a literal', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'const k = String(1)',
-        'wireScope({ [k]: {} } as any)',
+        'defineScope({ [k]: {} } as any)',
       ].join('\n')
     )
 
@@ -208,8 +208,8 @@ describe('addScope inspector', () => {
   test('is critical when a root is not an object literal', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { wireScope } from '@pikku/core/scope'",
-        "wireScope({ admin: 'nope' } as any)",
+        "import { defineScope } from '@pikku/core/scope'",
+        "defineScope({ admin: 'nope' } as any)",
       ].join('\n')
     )
 
@@ -223,7 +223,7 @@ describe('addScope inspector', () => {
 describe('validateScopeReferences', () => {
   const funcSource = (scopes: string, decls: string[] = []) =>
     [
-      "import { wireScope } from '@pikku/core/scope'",
+      "import { defineScope } from '@pikku/core/scope'",
       "import { pikkuSessionlessFunc } from '@pikku/core'",
       ...decls,
       'export const f = pikkuSessionlessFunc({',
@@ -235,7 +235,7 @@ describe('validateScopeReferences', () => {
   test('accepts a declared scope', async () => {
     const { criticals } = await inspectSource(
       funcSource("['admin:invoices:create']", [
-        'wireScope({',
+        'defineScope({',
         '  admin: {',
         '    scopes: { invoices: { scopes: { create: {} } } },',
         '  },',
@@ -249,7 +249,7 @@ describe('validateScopeReferences', () => {
   test('accepts an intermediate node of a declared tree', async () => {
     const { criticals } = await inspectSource(
       funcSource("['admin:invoices']", [
-        'wireScope({',
+        'defineScope({',
         '  admin: {',
         '    scopes: { invoices: { scopes: { create: {} } } },',
         '  },',
@@ -262,7 +262,7 @@ describe('validateScopeReferences', () => {
 
   test('rejects an undeclared scope', async () => {
     const { criticals } = await inspectSource(
-      funcSource("['billing:read']", ['wireScope({ admin: {} })'])
+      funcSource("['billing:read']", ['defineScope({ admin: {} })'])
     )
 
     assert.ok(
@@ -277,7 +277,7 @@ describe('validateScopeReferences', () => {
 
   test('lists the available scopes when one is undeclared', async () => {
     const { criticals } = await inspectSource(
-      funcSource("['nope']", ['wireScope({ admin: {} })'])
+      funcSource("['nope']", ['defineScope({ admin: {} })'])
     )
 
     assert.ok(
@@ -289,7 +289,7 @@ describe('validateScopeReferences', () => {
   test('rejects a typo in a nested scope', async () => {
     const { criticals } = await inspectSource(
       funcSource("['admin:invoice:create']", [
-        'wireScope({',
+        'defineScope({',
         '  admin: {',
         '    scopes: { invoices: { scopes: { create: {} } } },',
         '  },',
@@ -305,7 +305,7 @@ describe('validateScopeReferences', () => {
 
   test('accepts a wildcard requirement whose node is declared', async () => {
     const { criticals } = await inspectSource(
-      funcSource("['admin:*']", ['wireScope({ admin: {} })'])
+      funcSource("['admin:*']", ['defineScope({ admin: {} })'])
     )
 
     assert.deepEqual(criticals, [])
@@ -313,7 +313,7 @@ describe('validateScopeReferences', () => {
 
   test('rejects a wildcard requirement whose node is undeclared', async () => {
     const { criticals } = await inspectSource(
-      funcSource("['billing:*']", ['wireScope({ admin: {} })'])
+      funcSource("['billing:*']", ['defineScope({ admin: {} })'])
     )
 
     assert.ok(
@@ -324,7 +324,7 @@ describe('validateScopeReferences', () => {
 
   test('rejects a bare wildcard requirement', async () => {
     const { criticals } = await inspectSource(
-      funcSource("['*']", ['wireScope({ admin: {} })'])
+      funcSource("['*']", ['defineScope({ admin: {} })'])
     )
 
     assert.ok(

package/src/add/add-scope.ts

@@ -142,7 +142,7 @@ export const addScope: AddWiring = (logger, node, checker, state, _options) => {
   }
 
   const expression = node.expression
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireScope') {
+  if (!ts.isIdentifier(expression) || expression.text !== 'defineScope') {
     return
   }
 

package/src/add/add-secret.ts

@@ -1,7 +1,7 @@
 import { createAddKeyedWiring } from './add-keyed-wiring.js'
 
 export const addSecret = createAddKeyedWiring({
-  functionName: 'wireSecret',
+  functionName: 'defineSecret',
   idField: 'secretId',
   label: 'Secret',
   schemaPrefix: 'SecretSchema',