@pikku/inspector 0.12.50 → 0.12.54

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')
 
@@ -144,7 +144,7 @@ describe('pikkuScenarioStep', () => {
 
   test('the step target is bundled, so the step function is wired', async () => {
     const { state, cleanup } = await run([
-      "await scenario.step('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
     ])
     try {
       assert.ok(
@@ -183,7 +183,7 @@ describe('pikkuScenarioStep', () => {
   test('a non-literal step target is a PKU678 critical', async () => {
     const { criticals, cleanup } = await run([
       'const target = Math.random() > 0.5 ? "buysAnApple" : "seesAReceipt"',
-      "await scenario.step('buys something', target as any, {}, { actor: actors.shopper })",
+      "await scenario.when('buys something', target as any, {}, { actor: actors.shopper })",
     ])
     try {
       assert.ok(
@@ -209,6 +209,88 @@ 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 whose witness is an expectation helper is not flagged', async () => {
+    // `expectService` is an inline step and carries no phase, so it reaches
+    // PKU680 as nothing at all — but a recorded service call is a witness, and
+    // a flow that has one is not the assertion-free flow the rule is for.
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.expectService('the receipt was emailed', 'emailService.send', { actor: actors.shopper })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU680').length,
+        0,
+        `got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('an expectation parked in an uncalled helper is still no assertion', async () => {
+    const { criticals, cleanup } = await run([
+      'const neverCalled = async () => {',
+      "  await scenario.expectService('the receipt was emailed', 'emailService.send')",
+      '}',
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU680'),
+        `expected PKU680 — the helper never runs, so nothing is asserted; 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

@@ -35,12 +35,31 @@ const inspectSource = async (source: string) => {
   }
 }
 
+/** Inspects several files at once, keyed by basename. */
+const inspectSources = async (sources: Record<string, string>) => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-scope-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 })
+  }
+}
+
 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 +81,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 +109,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 +139,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 +153,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 +169,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')
     )
 
@@ -162,11 +181,65 @@ describe('addScope inspector', () => {
     )
   })
 
+  // The CLI generates a `defineScope` of its own — `user-admin.gen.ts` ships
+  // the whole `admin` tree, and `@pikku/addon-console` spells it out again — so
+  // a project that scaffolds user-admin declares scopes in more than one file
+  // and every one of them has to survive.
+  test('declarations in separate files all survive', async () => {
+    const { state, criticals } = await inspectSources({
+      'user-admin.gen.ts': [
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ admin: {} })',
+      ].join('\n'),
+      'scopes.ts': [
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ billing: {} })',
+      ].join('\n'),
+    })
+
+    assert.deepEqual(
+      criticals.filter((c) => /Only one defineScope/.test(c.message)),
+      [],
+      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(
+      state.scopes.definitions.map((d) => d.name).sort(),
+      ['admin', 'billing']
+    )
+  })
+
+  // The CLI scaffolds a scope tree of its own — `user-admin.gen.ts` declares the
+  // whole `admin` tree — so a generated declaration cannot be made to compete
+  // with the app's own for the single slot.
+  test('a generated declaration neither claims the slot nor conflicts', async () => {
+    const { state, criticals } = await inspectSources({
+      'user-admin.gen.ts': [
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ admin: {} })',
+      ].join('\n'),
+      'scopes.ts': [
+        "import { defineScope } from '@pikku/core/scope'",
+        'defineScope({ billing: {} })',
+      ].join('\n'),
+    })
+
+    assert.deepEqual(
+      criticals.filter((c) => c.code === ErrorCode.DUPLICATE_SCOPE_DEFINITION),
+      [],
+      `expected no duplicate critical, got ${JSON.stringify(criticals)}`
+    )
+    assert.deepEqual(
+      state.scopes.definitions.map((d) => d.name).sort(),
+      ['admin', 'billing'],
+      "both the generated tree and the app's own must survive"
+    )
+  })
+
   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 +252,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 +266,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 +281,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 +296,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 +308,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 +322,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 +335,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 +350,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 +362,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 +378,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 +386,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 +397,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',

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

@@ -0,0 +1,161 @@
+/**
+ * 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()
+    }
+  })
+})