@pikku/inspector 0.12.60 → 0.12.61

package/src/add/add-keyed-wiring.ts

@@ -7,13 +7,15 @@ import {
 import type { AddWiring, InspectorState } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
-import { parseDurationString } from '@pikku/core/ecosystem/types'
+import { parseDurationString } from '@pikku/core/utils'
 
 export interface KeyedWiringConfig {
   functionName: string
   idField: string
   label: string
   schemaPrefix: string
+  /** Boolean property carrying this wiring kind's deploy-gate opt-in/opt-out. */
+  flagField: string
   getState: (state: InspectorState) => {
     definitions: any[]
     files: Set<string>
@@ -49,17 +51,15 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
 
       const nameValue = getPropertyValue(obj, 'name') as string | null
       const displayNameValue = getPropertyValue(obj, 'displayName') as
-        | string
-        | null
+        string | null
       const descriptionValue = getPropertyValue(obj, 'description') as
-        | string
-        | null
+        string | null
       const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod') as
-        | string
-        | null
+        string | null
       const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
       const allowedHostsValue = getArrayPropertyValue(obj, 'allowedHosts')
       const idValue = getPropertyValue(obj, config.idField) as string | null
+      const flagValue = getPropertyValue(obj, config.flagField) === true
 
       let schemaVariableName: string | null = null
       let schemaSourceFile: string | null = null
@@ -171,6 +171,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
         docsUrl: docsUrlValue || undefined,
         allowedHosts: allowedHostsValue || undefined,
         [config.idField]: idValue,
+        [config.flagField]: flagValue || undefined,
         schema: schemaLookupName,
         sourceFile,
       })

package/src/add/add-permission.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import type { FunctionWiresMeta } from '@pikku/core/ecosystem/types'
+import type { FunctionWiresMeta } from '@pikku/core/function'
 import type { AddWiring } from '../types.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import {

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

@@ -57,8 +57,8 @@ const inspectSources = async (sources: Record<string, string>) => {
 /** The declared world every persona below is checked against. */
 const withRoles = (...lines: string[]) =>
   [
-    "import { defineScope } from '@pikku/core/ecosystem/scope'",
-    "import { defineSystemRole } from '@pikku/core/ecosystem/role'",
+    "import { defineScope } from '@pikku/core/scope'",
+    "import { defineSystemRole } from '@pikku/core/role'",
     "import { definePersonas } from '@pikku/core/persona'",
     'defineScope({ catalogue: { scopes: { read: {} } }, admin: {} })',
     'defineSystemRole({',
@@ -108,6 +108,30 @@ describe('addPersonas inspector', () => {
     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(

package/src/add/add-personas.ts

@@ -1,8 +1,7 @@
 import * as ts from 'typescript'
-import { DISPOSITIONS } from '@pikku/core/ecosystem/virtual-user'
+import { DISPOSITIONS } from '@pikku/core/virtual-user'
 import { isRunnablePersona } from '@pikku/core/persona'
-import type { PersonaMeta } from '@pikku/core/persona'
-import type { PersonaAccountMeta } from '@pikku/core/ecosystem/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'
@@ -266,6 +265,8 @@ export const addPersonas: AddWiring = (logger, node, _checker, state) => {
     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']
     }

package/src/add/add-scenario-step.test.ts

@@ -5,8 +5,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { inspect } from '../inspector.js'
 import type { InspectorLogger } from '../types.js'
-import type { WorkflowStepMeta } from '@pikku/core/ecosystem/workflow'
-import type { ScenarioStepMeta } from '@pikku/core/ecosystem/scenario'
+import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import type { ScenarioStepMeta } from '@pikku/core/scenario'
 
 function makeLogger(
   criticals: Array<{ code: string; message: string }>
@@ -39,6 +39,12 @@ const STEPS = [
   "  description: 'sees a receipt',",
   '  default: async ({ logger }) => ({ ok: true }),',
   '})',
+  'export const asksForTheReceipt = pikkuScenarioStep({',
+  "  name: 'asksForTheReceipt',",
+  "  description: 'asks for the receipt',",
+  '  actor: true,',
+  '  default: async ({ logger }) => ({ ok: true }),',
+  '})',
 ].join('\n')
 
 const scenarioSource = (body: string[], preamble: string[] = []) =>
@@ -210,6 +216,35 @@ describe('pikkuScenarioStep', () => {
     }
   })
 
+  test('a step declaring `actor: true` called without one is a PKU677 critical', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.then('asks for the receipt', 'asksForTheReceipt', {})",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU677'),
+        `a step that says it runs as somebody must be given somebody, browser binding or not, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a step that declares no actor is not flagged for running without one', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.then('sees a receipt', 'seesAReceipt', {})",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU677').length,
+        0,
+        `an assertion over an earlier step's value has nobody to be, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
   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 })",

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

@@ -58,7 +58,7 @@ describe('addScope inspector', () => {
   test('extracts a flat scope', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({',
         '  admin: {',
         "    displayName: 'Administration',",
@@ -81,7 +81,7 @@ describe('addScope inspector', () => {
   test('extracts a displayName at every depth', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({',
         '  admin: {',
         "    displayName: 'Administration',",
@@ -109,7 +109,7 @@ describe('addScope inspector', () => {
   test('extracts a nested scope tree', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({',
         '  admin: {',
         '    scopes: {',
@@ -139,7 +139,7 @@ describe('addScope inspector', () => {
   test('records the source file', async () => {
     const { state, file } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ admin: {} })',
       ].join('\n')
     )
@@ -153,7 +153,7 @@ describe('addScope inspector', () => {
   test('extracts several roots from one declaration', async () => {
     const { state, criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ admin: {}, billing: { scopes: { read: {} } } })',
       ].join('\n')
     )
@@ -169,7 +169,7 @@ describe('addScope inspector', () => {
   test('extracts several declarations', async () => {
     const { state } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ admin: {} })',
         'defineScope({ billing: {} })',
       ].join('\n')
@@ -188,11 +188,11 @@ describe('addScope inspector', () => {
   test('declarations in separate files all survive', async () => {
     const { state, criticals } = await inspectSources({
       'user-admin.gen.ts': [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ admin: {} })',
       ].join('\n'),
       'scopes.ts': [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ billing: {} })',
       ].join('\n'),
     })
@@ -214,11 +214,11 @@ describe('addScope inspector', () => {
   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/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ admin: {} })',
       ].join('\n'),
       'scopes.ts': [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'defineScope({ billing: {} })',
       ].join('\n'),
     })
@@ -238,7 +238,7 @@ describe('addScope inspector', () => {
   test('is critical when a root embeds the separator', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         "defineScope({ 'admin:users': {} })",
       ].join('\n')
     )
@@ -252,7 +252,7 @@ describe('addScope inspector', () => {
   test('is critical when a root is the wildcard', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         "defineScope({ '*': {} })",
       ].join('\n')
     )
@@ -266,7 +266,7 @@ describe('addScope inspector', () => {
   test('is critical when a root key is not a literal', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         'const k = String(1)',
         'defineScope({ [k]: {} } as any)',
       ].join('\n')
@@ -281,7 +281,7 @@ describe('addScope inspector', () => {
   test('is critical when a root is not an object literal', async () => {
     const { criticals } = await inspectSource(
       [
-        "import { defineScope } from '@pikku/core/ecosystem/scope'",
+        "import { defineScope } from '@pikku/core/scope'",
         "defineScope({ admin: 'nope' } as any)",
       ].join('\n')
     )
@@ -296,7 +296,7 @@ describe('addScope inspector', () => {
 describe('validateScopeReferences', () => {
   const funcSource = (scopes: string, decls: string[] = []) =>
     [
-      "import { defineScope } from '@pikku/core/ecosystem/scope'",
+      "import { defineScope } from '@pikku/core/scope'",
       "import { pikkuSessionlessFunc } from '@pikku/core'",
       ...decls,
       'export const f = pikkuSessionlessFunc({',

package/src/add/add-scope.ts

@@ -2,7 +2,7 @@ import * as ts from 'typescript'
 import { getPropertyValue } from '../utils/get-property-value.js'
 import type { AddWiring, InspectorLogger } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
-import type { ScopeNodeMeta } from '@pikku/core/ecosystem/scope'
+import type { ScopeNodeMeta } from '@pikku/core/scope'
 
 const SEPARATOR = ':'
 const WILDCARD = '*'
@@ -88,14 +88,12 @@ const extractScopeNodes = (
 
     const node: ScopeNodeMeta = {}
     const displayName = getPropertyValue(prop.initializer, 'displayName') as
-      | string
-      | null
+      string | null
     if (displayName) {
       node.displayName = displayName
     }
     const description = getPropertyValue(prop.initializer, 'description') as
-      | string
-      | null
+      string | null
     if (description) {
       node.description = description
     }
@@ -192,11 +190,9 @@ export const addScope: AddWiring = (logger, node, checker, state, _options) => {
 
     const root = prop.initializer
     const displayNameValue = getPropertyValue(root, 'displayName') as
-      | string
-      | null
+      string | null
     const descriptionValue = getPropertyValue(root, 'description') as
-      | string
-      | null
+      string | null
 
     let scopes: Record<string, ScopeNodeMeta> | undefined
     const scopesProp = root.properties.find(

package/src/add/add-secret.ts

@@ -5,5 +5,6 @@ export const addSecret = createAddKeyedWiring({
   idField: 'secretId',
   label: 'Secret',
   schemaPrefix: 'SecretSchema',
+  flagField: 'optional',
   getState: (state) => state.secrets,
 })

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

@@ -55,8 +55,8 @@ const inspectSources = async (sources: Record<string, string>) => {
 }
 
 const IMPORTS = [
-  "import { defineScope } from '@pikku/core/ecosystem/scope'",
-  "import { defineSystemRole } from '@pikku/core/ecosystem/role'",
+  "import { defineScope } from '@pikku/core/scope'",
+  "import { defineSystemRole } from '@pikku/core/role'",
 ]
 
 const withScopes = (...lines: string[]) =>
@@ -132,7 +132,7 @@ describe('addSystemRole inspector', () => {
         "defineSystemRole({ buyer: { scopes: ['catalogue:read'] } })"
       ),
       'more-roles.ts': [
-        "import { defineSystemRole } from '@pikku/core/ecosystem/role'",
+        "import { defineSystemRole } from '@pikku/core/role'",
         "defineSystemRole({ admin: { scopes: ['admin'] } })",
       ].join('\n'),
     })
@@ -153,7 +153,7 @@ describe('addSystemRole inspector', () => {
   test('a generated declaration neither claims the slot nor conflicts', async () => {
     const { state, criticals } = await inspectSources({
       'roles.gen.ts': [
-        "import { defineSystemRole } from '@pikku/core/ecosystem/role'",
+        "import { defineSystemRole } from '@pikku/core/role'",
         'defineSystemRole({ admin: { scopes: [] } })',
       ].join('\n'),
       'roles.ts': withScopes(

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

@@ -146,11 +146,9 @@ export const addSystemRole: AddWiring = (
     }
 
     const displayName = getPropertyValue(prop.initializer, 'displayName') as
-      | string
-      | null
+      string | null
     const description = getPropertyValue(prop.initializer, 'description') as
-      | string
-      | null
+      string | null
 
     state.systemRoles.files.add(sourceFile)
     state.systemRoles.definitions.push({

package/src/add/add-variable.ts

@@ -5,5 +5,6 @@ export const addVariable = createAddKeyedWiring({
   idField: 'variableId',
   label: 'Variable',
   schemaPrefix: 'VariableSchema',
+  flagField: 'required',
   getState: (state) => state.variables,
 })

package/src/add/add-wire-remote-addon.ts

@@ -45,7 +45,10 @@ export function addWireRemoteAddon(
     ) {
       hasAuth = true
       for (const authProp of prop.initializer.properties) {
-        if (!ts.isPropertyAssignment(authProp) || !ts.isIdentifier(authProp.name))
+        if (
+          !ts.isPropertyAssignment(authProp) ||
+          !ts.isIdentifier(authProp.name)
+        )
           continue
         if (
           authProp.name.text === 'credentialId' &&

package/src/add/add-workflow-graph-foreach.test.ts

@@ -0,0 +1,174 @@
+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'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+async function inspectGraph(graphSource: string[], graphName: string) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-foreach-'))
+  const stepFile = join(rootDir, 'my.steps.ts')
+  const graphFile = join(rootDir, 'my.graph.ts')
+
+  await writeFile(
+    stepFile,
+    [
+      "import { pikkuSessionlessFunc } from '@pikku/core'",
+      'export const listRows = pikkuSessionlessFunc({ func: async () => ({ rows: [] }) })',
+      'export const postVideo = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+    ].join('\n')
+  )
+  await writeFile(graphFile, graphSource.join('\n'))
+
+  try {
+    const state = await inspect(makeLogger(), [stepFile, graphFile], {
+      rootDir,
+    })
+    const graph = state.workflows.graphMeta[graphName]
+    assert.ok(graph, `graph meta '${graphName}' should be registered`)
+    return graph
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('addWorkflowGraph — forEach extraction', () => {
+  test('forEach node id and $item() lower into the serialized meta', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'foreach-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        "      forEach: 'listRows',",
+        '      input: (ref, template, $item) => ({',
+        "        url: $item('URL VIDEO'),",
+        '        whole: $item(),',
+        "        listed: ref('listRows'),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'foreach-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.deepEqual(node.forEach, { $ref: 'listRows' })
+    assert.equal(node.mode, undefined)
+    assert.deepEqual(node.input, {
+      url: { $ref: '$item', path: 'URL VIDEO' },
+      whole: { $ref: '$item', path: undefined },
+      listed: { $ref: 'listRows', path: undefined },
+    })
+  })
+
+  test('forEach accepts a (ref) callback with a path, plus a sequential mode', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'foreach-callback-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        "      forEach: (ref) => ref('listRows', 'rows'),",
+        "      mode: 'sequential',",
+        "      input: (ref, template, $item) => ({ url: $item('URL') }),",
+        '    },',
+        '  },',
+        '})',
+      ],
+      'foreach-callback-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.deepEqual(node.forEach, { $ref: 'listRows', path: 'rows' })
+    assert.equal(node.mode, 'sequential')
+  })
+
+  test('an existing (ref) => ... node keeps its exact input and gains no forEach', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        "import { template } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'plain-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        '      input: (ref) => ({',
+        "        rows: ref('listRows', 'rows'),",
+        "        label: template('rows: $0', [ref('listRows', 'rows')]),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'plain-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.equal(node.forEach, undefined)
+    assert.equal(node.mode, undefined)
+    assert.deepEqual(node.input, {
+      rows: { $ref: 'listRows', path: 'rows' },
+      label: {
+        $template: {
+          parts: ['rows: ', ''],
+          expressions: [{ $ref: 'listRows', path: 'rows' }],
+        },
+      },
+    })
+  })
+
+  test('an existing (ref, template) => ... node still resolves template from the 2nd param', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'two-param-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        '      input: (ref, template) => ({',
+        "        label: template('rows: $0', [ref('listRows', 'rows')]),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'two-param-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.equal(node.forEach, undefined)
+    assert.deepEqual(node.input, {
+      label: {
+        $template: {
+          parts: ['rows: ', ''],
+          expressions: [{ $ref: 'listRows', path: 'rows' }],
+        },
+      },
+    })
+  })
+})

package/src/add/add-workflow-graph-input.test.ts

@@ -36,7 +36,7 @@ describe('addWorkflowGraph — node input extraction', () => {
       graphFile,
       [
         "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
-        "import { template } from '@pikku/core/ecosystem/workflow'",
+        "import { template } from '@pikku/core/workflow'",
         'export const myGraph = pikkuWorkflowGraph({',
         "  name: 'input-graph',",
         "  nodes: { edit: 'edit' },",