@pikku/inspector 0.12.50 → 0.12.52

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',

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()
+    }
+  })
+})

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

@@ -0,0 +1,214 @@
+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 })
+  }
+}
+
+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('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)))
+  })
+})