@pikku/inspector 0.12.74 → 0.12.81

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

@@ -1,406 +0,0 @@
-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('the app a person signs into survives into the meta', async () => {
-    const { state, criticals } = await inspectSource(
-      withRoles(
-        'definePersonas({',
-        '  susan: {',
-        "    name: 'Susan',",
-        "    app: 'storefront',",
-        '  },',
-        '})'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.equal(state.personas.definitions[0]!.app, 'storefront')
-  })
-
-  test('a person who names no app has none, rather than a guessed one', async () => {
-    const { state } = await inspectSource(
-      withRoles('definePersonas({', "  susan: { name: 'Susan' },", '})')
-    )
-
-    assert.equal(state.personas.definitions[0]!.app, undefined)
-  })
-
-  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

@@ -1,287 +0,0 @@
-import * as ts from 'typescript'
-import { DISPOSITIONS } from '@pikku/core/virtual-user'
-import { isRunnablePersona } from '@pikku/core/persona'
-import type { PersonaMeta, PersonaAccountMeta } 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
-    const app = stringProperty(config, 'app')
-    if (app !== undefined) persona.app = app
-    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)
-  }
-}