@pikku/inspector 0.12.50 → 0.12.54

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

@@ -0,0 +1,382 @@
+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 { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+const inspectSource = async (source: string) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-personas-'))
+  const file = join(rootDir, 'personas.ts')
+  await writeFile(file, source)
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), [file], { rootDir })
+    return { state, criticals }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+/** Inspects several files at once, keyed by basename. */
+const inspectSources = async (sources: Record<string, string>) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-personas-multi-'))
+  const files: Record<string, string> = {}
+  for (const [name, source] of Object.entries(sources)) {
+    files[name] = join(rootDir, name)
+    await writeFile(files[name]!, source)
+  }
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), Object.values(files), {
+      rootDir,
+    })
+    return { state, criticals, files }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+/** The declared world every persona below is checked against. */
+const withRoles = (...lines: string[]) =>
+  [
+    "import { defineScope } from '@pikku/core/scope'",
+    "import { defineSystemRole } from '@pikku/core/role'",
+    "import { definePersonas } from '@pikku/core/persona'",
+    'defineScope({ catalogue: { scopes: { read: {} } }, admin: {} })',
+    'defineSystemRole({',
+    "  buyer: { scopes: ['catalogue:read'] },",
+    "  admin: { scopes: ['admin'] },",
+    '})',
+    ...lines,
+  ].join('\n')
+
+describe('addPersonas inspector', () => {
+  test('extracts a whole person', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        '  susan: {',
+        "    name: 'Susan',",
+        "    jobTitle: 'Buys for a small café',",
+        "    roles: ['buyer'],",
+        "    personality: 'Hunts cheap deals.',",
+        "    goals: ['Get the weekly order in under five minutes'],",
+        "    tags: ['commerce'],",
+        "    disposition: 'careless',",
+        '    tuning: { repeatRate: 0.3 },',
+        "    fixtures: ['seedCatalogue'],",
+        '    account: {},',
+        '  },',
+        '})'
+      )
+    )
+
+    assert.deepEqual(criticals, [])
+    assert.equal(state.personas.definitions.length, 1)
+    const susan = state.personas.definitions[0]!
+    assert.equal(susan.id, 'susan')
+    assert.equal(susan.name, 'Susan')
+    assert.equal(susan.jobTitle, 'Buys for a small café')
+    assert.deepEqual(susan.roles, ['buyer'])
+    assert.equal(susan.personality, 'Hunts cheap deals.')
+    assert.deepEqual(susan.goals, [
+      'Get the weekly order in under five minutes',
+    ])
+    assert.deepEqual(susan.tags, ['commerce'])
+    assert.equal(susan.disposition, 'careless')
+    assert.deepEqual(susan.tuning, { repeatRate: 0.3 })
+    assert.deepEqual(susan.fixtures, ['seedCatalogue'])
+    assert.deepEqual(susan.account, {})
+    assert.equal(susan.runnable, true)
+  })
+
+  test('extracts a declared avatar', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        '  susan: {',
+        "    name: 'Susan',",
+        "    avatarUrl: '/avatars/susan.png',",
+        '  },',
+        '})'
+      )
+    )
+    assert.equal(state.personas.definitions[0]!.avatarUrl, '/avatars/susan.png')
+  })
+
+  // The console draws a colour-and-icon avatar from the persona's id when none
+  // is declared, so an absent field has to stay absent rather than become an
+  // empty string the renderer would treat as a broken image.
+  test('leaves the avatar absent when none is declared', async () => {
+    const { state } = await inspectSource(
+      withRoles('definePersonas({', "  susan: { name: 'Susan' },", '})')
+    )
+    assert.equal(state.personas.definitions[0]!.avatarUrl, undefined)
+  })
+
+  test('extracts the environments a persona declares', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        '  robin: {',
+        "    name: 'Robin',",
+        "    disposition: 'accountable',",
+        "    environments: ['staging', 'prod'],",
+        '  },',
+        '})'
+      )
+    )
+    assert.deepEqual(state.personas.definitions[0]!.environments, [
+      'staging',
+      'prod',
+    ])
+  })
+
+  // "Everywhere but production" is a fact about the config, and the meta file
+  // outlives whichever environments were configured the day it was written —
+  // so the absence is preserved rather than resolved into a list here.
+  test('leaves environments absent when none are declared', async () => {
+    const { state } = await inspectSource(
+      withRoles('definePersonas({', "  susan: { name: 'Susan' },", '})')
+    )
+    assert.equal(state.personas.definitions[0]!.environments, undefined)
+  })
+
+  test('the declaration key is the id', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  susan: { name: 'Susan' },",
+        "  mallory: { name: 'Mallory' },",
+        '})'
+      )
+    )
+    assert.deepEqual(
+      state.personas.definitions.map((p) => p.id),
+      ['susan', 'mallory']
+    )
+  })
+
+  test('a persona without a name is refused', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles('definePersonas({', "  susan: { roles: ['buyer'] },", '})')
+    )
+    assert.equal(state.personas.definitions.length, 0)
+    assert.ok(criticals.some((c) => /needs a literal 'name'/.test(c.message)))
+  })
+
+  test('an unknown disposition is refused rather than defaulted', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  susan: { name: 'Susan', disposition: 'grumpy' },",
+        '})'
+      )
+    )
+    assert.equal(state.personas.definitions.length, 0)
+    assert.ok(
+      criticals.some((c) => /unknown disposition 'grumpy'/.test(c.message))
+    )
+  })
+
+  // `repeatRate: 18` meaning 18% would silently double every call, and the run
+  // would read as a product bug.
+  test('a tuning dial outside its range is refused', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  susan: { name: 'Susan', tuning: { repeatRate: 18 } },",
+        '})'
+      )
+    )
+    assert.equal(state.personas.definitions.length, 0)
+    assert.ok(
+      criticals.some((c) =>
+        /repeatRate must be between 0 and 1/.test(c.message)
+      )
+    )
+  })
+
+  test('a linked account is extracted alongside the primary one', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        '  yasser: {',
+        "    name: 'Yasser',",
+        '    account: {},',
+        "    linkedAccounts: { google: { provider: 'google' } },",
+        '  },',
+        '})'
+      )
+    )
+    assert.deepEqual(criticals, [])
+    const yasser = state.personas.definitions[0]!
+    assert.deepEqual(yasser.account, {})
+    assert.deepEqual(yasser.linkedAccounts, { google: { provider: 'google' } })
+    // Their primary login is email+password, so they can still be driven.
+    assert.equal(yasser.runnable, true)
+  })
+
+  // Driving a consent screen needs a human — refused at the CLI rather than
+  // failing somewhere inside a browser.
+  test('a persona whose own login is a provider is not runnable', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  yasser: { name: 'Yasser', account: { provider: 'google' } },",
+        '})'
+      )
+    )
+    assert.equal(state.personas.definitions[0]!.runnable, false)
+  })
+
+  test('a person who is only ever acted upon says so', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  target: { name: 'Target', account: {}, runnable: false },",
+        '})'
+      )
+    )
+    assert.equal(state.personas.definitions[0]!.runnable, false)
+  })
+
+  // One call site per codebase, so there is one place to read the cast from
+  // and one place to add to. The keyed form above is how you declare more.
+  test('a second definePersonas in the same file is refused', async () => {
+    const { state, criticals } = await inspectSource(
+      withRoles(
+        "definePersonas({ susan: { name: 'Susan' } })",
+        "definePersonas({ dave: { name: 'Dave' } })"
+      )
+    )
+
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.DUPLICATE_PERSONAS_DEFINITION
+    )
+    assert.ok(
+      hit,
+      `expected DUPLICATE_PERSONAS_DEFINITION, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(
+      state.personas.definitions.map((p) => p.id),
+      ['susan']
+    )
+  })
+
+  test('a second definePersonas in another file is refused', async () => {
+    const { criticals, files } = await inspectSources({
+      'personas.ts': withRoles("definePersonas({ susan: { name: 'Susan' } })"),
+      'more-personas.ts': [
+        "import { definePersonas } from '@pikku/core/persona'",
+        "definePersonas({ dave: { name: 'Dave' } })",
+      ].join('\n'),
+    })
+
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.DUPLICATE_PERSONAS_DEFINITION
+    )
+    assert.ok(
+      hit,
+      `expected DUPLICATE_PERSONAS_DEFINITION, got ${JSON.stringify(criticals)}`
+    )
+    assert.ok(
+      hit!.message.includes(files['personas.ts']!) &&
+        hit!.message.includes(files['more-personas.ts']!),
+      `expected both files named, got ${hit!.message}`
+    )
+  })
+
+  // The CLI scaffolds personas of its own, and nobody adds a persona to a file
+  // the next codegen run overwrites — so a generated declaration neither takes
+  // the single slot nor collides with the app's own.
+  test('a generated declaration neither claims the slot nor conflicts', async () => {
+    const { state, criticals } = await inspectSources({
+      'pikku-personas.gen.ts': [
+        "import { definePersonas } from '@pikku/core/persona'",
+        "definePersonas({ dave: { name: 'Dave' } })",
+      ].join('\n'),
+      'personas.ts': withRoles("definePersonas({ susan: { name: 'Susan' } })"),
+    })
+
+    assert.deepEqual(
+      criticals.filter(
+        (c) => c.code === ErrorCode.DUPLICATE_PERSONAS_DEFINITION
+      ),
+      [],
+      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(state.personas.definitions.map((d) => d.id).sort(), [
+      'dave',
+      'susan',
+    ])
+  })
+
+  // A half-read roles array typechecks, runs, and grants less than the source
+  // says — so an unreadable one reads as absent.
+  test('a computed roles array is not half-extracted', async () => {
+    const { state } = await inspectSource(
+      withRoles(
+        'const r = "buyer"',
+        'definePersonas({',
+        "  susan: { name: 'Susan', roles: ['buyer', r] },",
+        '})'
+      )
+    )
+    assert.deepEqual(state.personas.definitions[0]!.roles, [])
+  })
+})
+
+describe('validatePersonaRoles', () => {
+  test('a declared system role is accepted', async () => {
+    const { criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  susan: { name: 'Susan', roles: ['buyer', 'admin'] },",
+        '})'
+      )
+    )
+    assert.deepEqual(criticals, [])
+  })
+
+  // The failure this prevents: an admin deletes 'invoicing-clerk' from the
+  // console, and Susan goes on claiming to test it while 403ing everywhere.
+  test('a role that is not declared fails the build', async () => {
+    const { criticals } = await inspectSource(
+      withRoles(
+        'definePersonas({',
+        "  susan: { name: 'Susan', roles: ['invoicing-clerk'] },",
+        '})'
+      )
+    )
+    const critical = criticals.find((c) => /invoicing-clerk/.test(c.message))
+    assert.ok(critical, `expected a critical, got ${JSON.stringify(criticals)}`)
+    assert.match(critical!.message, /may only name a system role/)
+    assert.match(critical!.message, /admin, buyer/)
+  })
+
+  test('a persona with no roles at all is fine', async () => {
+    const { criticals } = await inspectSource(
+      withRoles('definePersonas({', "  susan: { name: 'Susan' },", '})')
+    )
+    assert.deepEqual(criticals, [])
+  })
+})

package/src/add/add-personas.ts

@@ -0,0 +1,285 @@
+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 { claimSingleDeclaration } from '../utils/single-declaration.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
+
+  if (
+    !claimSingleDeclaration(
+      logger,
+      state.personas.files,
+      ErrorCode.DUPLICATE_PERSONAS_DEFINITION,
+      'definePersonas',
+      sourceFile
+    )
+  ) {
+    return
+  }
+
+  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 avatarUrl = stringProperty(config, 'avatarUrl')
+    if (avatarUrl !== undefined) persona.avatarUrl = avatarUrl
+    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.definitions.push(persona)
+  }
+}