@pikku/inspector 0.12.75 → 0.12.81

package/src/add/add-subject-scenario-steps.test.ts

@@ -1,161 +0,0 @@
-/**
- * The two step kinds whose subject is not a person: the app acting on itself,
- * and a third-party system acting on it.
- *
- * What is being pinned here is mostly negative — that neither can declare a
- * surface, and that both are marked in a way the virtual-user catalogue can
- * refuse. The second is not tidiness: a virtual user that could invoke "Stripe's
- * webhook arrives" would forge its own payment success, and every finding
- * downstream of that is worthless.
- */
-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'
-
-async function run(source: string) {
-  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-subject-step-'))
-  const file = join(rootDir, 'subjects.steps.ts')
-  await writeFile(file, source)
-  const errors: string[] = []
-  const logger = {
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: (message: string) => {
-      errors.push(message)
-    },
-    diagnostic: () => {},
-    critical: (_code: any, message: string) => {
-      errors.push(message)
-    },
-    hasCriticalErrors: () => false,
-  } as unknown as InspectorLogger
-
-  const state = await inspect(logger, [file], { rootDir })
-  return {
-    state,
-    errors,
-    cleanup: () => rm(rootDir, { recursive: true, force: true }),
-  }
-}
-
-const IMPORTS =
-  "import { pikkuPlatformScenarioStep, pikkuAddonScenarioStep } from '@pikku/core/workflow'"
-
-describe('pikkuPlatformScenarioStep', () => {
-  test('registers under its declared name, marked as the platform acting', async () => {
-    const { state, errors, cleanup } = await run(
-      [
-        IMPORTS,
-        'export const trialHasExpired = pikkuPlatformScenarioStep({',
-        "  name: 'trialHasExpired',",
-        "  description: 'the platform has expired the trial',",
-        '  func: async ({ logger }, data: { orgId: string }) => ({ ok: !!data.orgId }),',
-        '})',
-      ].join('\n')
-    )
-    try {
-      assert.deepEqual(errors, [])
-      const meta = state.functions.meta['trialHasExpired']
-      assert.ok(meta, 'expected a function registered as trialHasExpired')
-      assert.equal(meta.scenarioStepKind, 'platform')
-      // Held out of every deployed unit, exactly like a persona step.
-      assert.equal(meta.scenarioStep, true)
-      assert.equal(state.rpc.exposedMeta['trialHasExpired'], undefined)
-      assert.equal(state.rpc.internalMeta['trialHasExpired'], undefined)
-    } finally {
-      await cleanup()
-    }
-  })
-
-  test('has exactly one witness: a surface binding is refused', async () => {
-    const { state, errors, cleanup } = await run(
-      [
-        IMPORTS,
-        'export const trialHasExpired = pikkuPlatformScenarioStep({',
-        "  name: 'trialHasExpired',",
-        '  browser: async ({ logger }) => ({ ok: true }),',
-        '})',
-      ].join('\n')
-    )
-    try {
-      assert.ok(
-        errors.some((message) => message.includes('browser')),
-        `expected the browser binding to be refused, got: ${errors.join(' | ')}`
-      )
-      assert.equal(state.functions.meta['trialHasExpired'], undefined)
-    } finally {
-      await cleanup()
-    }
-  })
-
-  test('declares one surface, so a browser run never demands an actor for it', async () => {
-    const { state, cleanup } = await run(
-      [
-        IMPORTS,
-        'export const trialHasExpired = pikkuPlatformScenarioStep({',
-        "  name: 'trialHasExpired',",
-        '  func: async ({ logger }) => ({ ok: true }),',
-        '})',
-      ].join('\n')
-    )
-    try {
-      assert.deepEqual(
-        state.functions.meta['trialHasExpired']?.scenarioStepSurfaces,
-        ['default']
-      )
-    } finally {
-      await cleanup()
-    }
-  })
-})
-
-describe('pikkuAddonScenarioStep', () => {
-  test('records the addon whose system acts', async () => {
-    const { state, errors, cleanup } = await run(
-      [
-        IMPORTS,
-        'export const stripeWebhookArrives = pikkuAddonScenarioStep({',
-        "  name: 'stripeWebhookArrives',",
-        "  addon: 'stripe',",
-        "  template: 'Stripe sends {event}',",
-        '  func: async ({ logger }, data: { event: string }) => ({ ok: !!data.event }),',
-        '})',
-      ].join('\n')
-    )
-    try {
-      assert.deepEqual(errors, [])
-      const meta = state.functions.meta['stripeWebhookArrives']
-      assert.equal(meta?.scenarioStepKind, 'addon')
-      assert.equal(meta?.scenarioStepAddon, 'stripe')
-      assert.equal(meta?.scenarioStepTemplate, 'Stripe sends {event}')
-    } finally {
-      await cleanup()
-    }
-  })
-
-  test('without an addon it is refused — nobody can say whose system acted', async () => {
-    const { state, errors, cleanup } = await run(
-      [
-        IMPORTS,
-        'export const stripeWebhookArrives = pikkuAddonScenarioStep({',
-        "  name: 'stripeWebhookArrives',",
-        '  func: async ({ logger }) => ({ ok: true }),',
-        '})',
-      ].join('\n')
-    )
-    try {
-      assert.ok(
-        errors.some((message) => message.includes('addon')),
-        `expected a missing-addon error, got: ${errors.join(' | ')}`
-      )
-      assert.equal(state.functions.meta['stripeWebhookArrives'], undefined)
-    } finally {
-      await cleanup()
-    }
-  })
-})

package/src/add/add-system-role.test.ts

@@ -1,297 +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 type { 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-role-'))
-  const file = join(rootDir, 'roles.ts')
-  await writeFile(file, source)
-  const criticals: Array<{ code: ErrorCode; message: string }> = []
-  try {
-    const state = await inspect(makeLogger(criticals), [file], { rootDir })
-    return { state, criticals, file }
-  } 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-role-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 })
-  }
-}
-
-const IMPORTS = [
-  "import { defineScope } from '@pikku/core/scope'",
-  "import { defineSystemRole } from '@pikku/core/role'",
-]
-
-const withScopes = (...lines: string[]) =>
-  [
-    ...IMPORTS,
-    'defineScope({',
-    '  catalogue: { scopes: { read: {} } },',
-    '  orders: { scopes: { create: {} } },',
-    '  admin: { scopes: { users: { scopes: { ban: {} } } } },',
-    '})',
-    ...lines,
-  ].join('\n')
-
-describe('addSystemRole inspector', () => {
-  test('extracts a role with its scopes', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        '  buyer: {',
-        "    displayName: 'Buyer',",
-        "    description: 'Browses and orders',",
-        "    scopes: ['catalogue:read', 'orders:create'],",
-        '  },',
-        '})'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.equal(state.systemRoles.definitions.length, 1)
-    const role = state.systemRoles.definitions[0]!
-    assert.equal(role.name, 'buyer')
-    assert.equal(role.displayName, 'Buyer')
-    assert.equal(role.description, 'Browses and orders')
-    assert.deepEqual(role.scopes, ['catalogue:read', 'orders:create'])
-  })
-
-  test('extracts several roles from one call', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  buyer: { scopes: ['catalogue:read'] },",
-        "  admin: { scopes: ['admin'] },",
-        '})'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.deepEqual(
-      state.systemRoles.definitions.map((r) => r.name),
-      ['buyer', 'admin']
-    )
-  })
-
-  test('extracts roles from several calls in one file', async () => {
-    const { state } = await inspectSource(
-      withScopes(
-        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })",
-        "defineSystemRole({ admin: { scopes: ['admin'] } })"
-      )
-    )
-
-    assert.deepEqual(state.systemRoles.definitions.map((r) => r.name).sort(), [
-      'admin',
-      'buyer',
-    ])
-  })
-
-  // Roles follow scopes: a project scaffolding user-admin has a generated
-  // declaration beside its own, so every file's roles have to survive.
-  test('declarations in separate files all survive', async () => {
-    const { state, criticals } = await inspectSources({
-      'roles.ts': withScopes(
-        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })"
-      ),
-      'more-roles.ts': [
-        "import { defineSystemRole } from '@pikku/core/role'",
-        "defineSystemRole({ admin: { scopes: ['admin'] } })",
-      ].join('\n'),
-    })
-
-    assert.deepEqual(
-      criticals.filter((c) => /Only one defineSystemRole/.test(c.message)),
-      [],
-      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
-    )
-    assert.deepEqual(state.systemRoles.definitions.map((r) => r.name).sort(), [
-      'admin',
-      'buyer',
-    ])
-  })
-
-  // A generated file is not the one place a person adds a role to, so it neither
-  // takes the single slot nor collides with the app's own declaration.
-  test('a generated declaration neither claims the slot nor conflicts', async () => {
-    const { state, criticals } = await inspectSources({
-      'roles.gen.ts': [
-        "import { defineSystemRole } from '@pikku/core/role'",
-        'defineSystemRole({ admin: { scopes: [] } })',
-      ].join('\n'),
-      'roles.ts': withScopes(
-        "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })"
-      ),
-    })
-
-    assert.deepEqual(
-      criticals.filter(
-        (c) => c.code === ErrorCode.DUPLICATE_SYSTEM_ROLE_DEFINITION
-      ),
-      [],
-      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
-    )
-    assert.deepEqual(state.systemRoles.definitions.map((r) => r.name).sort(), [
-      'admin',
-      'buyer',
-    ])
-  })
-
-  test('a role granting nothing is legitimate, said explicitly', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes('defineSystemRole({', '  guest: { scopes: [] },', '})')
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.deepEqual(state.systemRoles.definitions[0]!.scopes, [])
-  })
-
-  // Omitting `scopes` is not the same as declaring none — one is a decision,
-  // the other is a role nobody finished writing.
-  test('omitting scopes entirely is refused', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes('defineSystemRole({', "  guest: { description: 'x' },", '})')
-    )
-
-    assert.equal(state.systemRoles.definitions.length, 0)
-    assert.ok(criticals.some((c) => /has no 'scopes'/.test(c.message)))
-  })
-
-  test('a name containing the scope separator is refused', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes('defineSystemRole({', "  'admin:users': { scopes: [] },", '})')
-    )
-
-    assert.equal(state.systemRoles.definitions.length, 0)
-    assert.ok(criticals.some((c) => /separator/.test(c.message)))
-  })
-
-  // Scopes are read by AST, so a computed entry cannot be checked against the
-  // declared set — accepting it silently would let a role grant anything.
-  test('a computed scope entry is refused', async () => {
-    const { criticals } = await inspectSource(
-      withScopes(
-        'const s = "catalogue:read"',
-        'defineSystemRole({',
-        '  buyer: { scopes: [s] },',
-        '})'
-      )
-    )
-
-    assert.ok(criticals.some((c) => /not a string literal/.test(c.message)))
-  })
-
-  test('`as const` does not hide the declaration', async () => {
-    const { state, criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  buyer: { scopes: ['catalogue:read'] },",
-        '} as const)'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-    assert.equal(state.systemRoles.definitions.length, 1)
-  })
-})
-
-describe('validateSystemRoleScopes', () => {
-  test('accepts declared scopes, including an intermediate node', async () => {
-    const { criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  admin: { scopes: ['admin', 'admin:users:ban'] },",
-        '})'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-
-  test('accepts a subtree wildcard whose node exists', async () => {
-    const { criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  admin: { scopes: ['admin:*'] },",
-        '})'
-      )
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-
-  // The failure this exists to prevent: no function checks `orders:refund`, so
-  // a persona holding the role passes every call and the boundary the role
-  // describes is never exercised.
-  test('an undeclared scope fails the build and lists what is available', async () => {
-    const { criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  buyer: { scopes: ['orders:refund'] },",
-        '})'
-      )
-    )
-
-    const critical = criticals.find((c) => /orders:refund/.test(c.message))
-    assert.ok(critical, `expected a critical, got ${JSON.stringify(criticals)}`)
-    assert.match(critical!.message, /is not declared/)
-    assert.match(critical!.message, /catalogue:read/)
-  })
-
-  test('a subtree wildcard on an undeclared node fails', async () => {
-    const { criticals } = await inspectSource(
-      withScopes(
-        'defineSystemRole({',
-        "  buyer: { scopes: ['nonsense:*'] },",
-        '})'
-      )
-    )
-
-    assert.ok(criticals.some((c) => /nonsense:\*/.test(c.message)))
-  })
-
-  test('the bare wildcard is refused — it hides what the role confers', async () => {
-    const { criticals } = await inspectSource(
-      withScopes('defineSystemRole({', "  god: { scopes: ['*'] },", '})')
-    )
-
-    assert.ok(criticals.some((c) => /bare wildcard/.test(c.message)))
-  })
-})

package/src/add/add-system-role.ts

@@ -1,162 +0,0 @@
-import * as ts from 'typescript'
-import { getPropertyValue } from '../utils/get-property-value.js'
-import type { AddWiring } from '../types.js'
-import { ErrorCode } from '../error-codes.js'
-
-const SEPARATOR = ':'
-
-/**
- * Unwraps `x as const` / `x satisfies T` so a cast declaration is still
- * extracted rather than silently skipped.
- */
-const unwrapAs = (node: ts.Expression): ts.Expression =>
-  ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
-    ? unwrapAs(node.expression)
-    : node
-
-/**
- * Reads a `scopes: [...]` array of string literals.
- *
- * Returns `undefined` rather than an empty array when the property is absent
- * or unreadable, so the caller can tell "declared no scopes" from "we could
- * not see the scopes" — the first is a legitimate placeholder role, the second
- * would silently produce one.
- */
-const extractScopes = (
-  obj: ts.ObjectLiteralExpression,
-  roleName: string,
-  logger: Parameters<AddWiring>[0]
-): string[] | undefined => {
-  const prop = obj.properties.find(
-    (p) =>
-      ts.isPropertyAssignment(p) &&
-      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
-      p.name.text === 'scopes'
-  )
-
-  if (!prop) {
-    logger.critical(
-      ErrorCode.INVALID_VALUE,
-      `System role '${roleName}' has no 'scopes'. A role that grants nothing should say so with 'scopes: []'.`
-    )
-    return undefined
-  }
-
-  if (
-    !ts.isPropertyAssignment(prop) ||
-    !ts.isArrayLiteralExpression(prop.initializer)
-  ) {
-    logger.critical(
-      ErrorCode.INVALID_VALUE,
-      `System role '${roleName}' must declare 'scopes' as an array literal.`
-    )
-    return undefined
-  }
-
-  const scopes: string[] = []
-  for (const element of prop.initializer.elements) {
-    const unwrapped = unwrapAs(element)
-    if (!ts.isStringLiteral(unwrapped)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `System role '${roleName}' lists a scope that is not a string literal. ` +
-          `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`
-      )
-      continue
-    }
-    scopes.push(unwrapped.text)
-  }
-  return scopes
-}
-
-export const addSystemRole: AddWiring = (
-  logger,
-  node,
-  _checker,
-  state,
-  _options
-) => {
-  if (!ts.isCallExpression(node)) {
-    return
-  }
-
-  const expression = node.expression
-  if (!ts.isIdentifier(expression) || expression.text !== 'defineSystemRole') {
-    return
-  }
-
-  const firstArg = node.arguments[0]
-  if (!firstArg) {
-    return
-  }
-
-  const unwrapped = unwrapAs(firstArg)
-  if (!ts.isObjectLiteralExpression(unwrapped)) {
-    return
-  }
-
-  const sourceFile = node.getSourceFile().fileName
-
-  for (const prop of unwrapped.properties) {
-    if (!ts.isPropertyAssignment(prop)) {
-      continue
-    }
-
-    let name: string | undefined
-    if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
-      name = prop.name.text
-    }
-
-    if (name === undefined) {
-      logger.critical(
-        ErrorCode.NON_LITERAL_WIRE_NAME,
-        'A system role is declared with a key that is not a literal.'
-      )
-      continue
-    }
-
-    if (name.length === 0) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        'A system role is declared with an empty name.'
-      )
-      continue
-    }
-
-    if (name.includes(SEPARATOR)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `System role '${name}' contains the '${SEPARATOR}' separator. ` +
-          `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`
-      )
-      continue
-    }
-
-    if (!ts.isObjectLiteralExpression(prop.initializer)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `System role '${name}' must be an object literal.`
-      )
-      continue
-    }
-
-    const scopes = extractScopes(prop.initializer, name, logger)
-    if (scopes === undefined) {
-      continue
-    }
-
-    const displayName = getPropertyValue(prop.initializer, 'displayName') as
-      string | null
-    const description = getPropertyValue(prop.initializer, 'description') as
-      string | null
-
-    state.systemRoles.files.add(sourceFile)
-    state.systemRoles.definitions.push({
-      name,
-      displayName: displayName || undefined,
-      description: description || undefined,
-      scopes,
-      sourceFile,
-    })
-  }
-}