@pikku/inspector 0.12.49 → 0.12.52

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

@@ -0,0 +1,196 @@
+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, MiddlewareGroupMeta } 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
+
+/** Every file that registered middleware for one pattern or tag. */
+const sourceFiles = (group: MiddlewareGroupMeta | undefined): string[] =>
+  group
+    ? [
+        group.sourceFile,
+        ...(group.additionalRegistrations ?? []).map((r) => r.sourceFile),
+      ]
+    : []
+
+/** Runs the inspector over files written into a throwaway directory. */
+const withProject = async (
+  prefix: string,
+  files: Record<string, string[]>,
+  assertions: (state: Awaited<ReturnType<typeof inspect>>) => void
+) => {
+  const rootDir = await mkdtemp(join(tmpdir(), prefix))
+  const paths: string[] = []
+  for (const [name, lines] of Object.entries(files)) {
+    const path = join(rootDir, name)
+    await writeFile(path, lines.join('\n'))
+    paths.push(path)
+  }
+  try {
+    assertions(await inspect(makeLogger([]), paths, { rootDir }))
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('addMiddleware inspector', () => {
+  describe('two files registering the same HTTP pattern', () => {
+    // The group is keyed by pattern, so the second call used to overwrite the
+    // first. Codegen emits imports from what is stored, so the losing file was
+    // never imported and its middleware never registered — an app could lose
+    // its session bridge to an unrelated '*' group and see nothing go wrong
+    // until a request arrived without a session.
+    const project = {
+      'session.ts': [
+        "import { addHTTPMiddleware, pikkuMiddleware } from '#pikku'",
+        'export const sessionMiddleware = () =>',
+        "  addHTTPMiddleware('*', [",
+        '    pikkuMiddleware(async (_s, _w, next) => next()),',
+        '  ])',
+      ],
+      'logging.ts': [
+        "import { addHTTPMiddleware, pikkuMiddleware } from '#pikku'",
+        'export const loggingMiddleware = () =>',
+        "  addHTTPMiddleware('*', [",
+        '    pikkuMiddleware(async (_s, _w, next) => next()),',
+        '  ])',
+      ],
+    }
+
+    test('keeps both registrations', async () => {
+      await withProject('pikku-mw-http-collide-', project, (state) => {
+        const group = state.http.routeMiddleware.get('*')
+        assert.ok(group, "expected a group for '*'")
+        assert.equal(
+          sourceFiles(group).length,
+          2,
+          'both files must survive, or one middleware silently stops running'
+        )
+      })
+    })
+
+    test('keeps both export names, so both can be imported', async () => {
+      await withProject('pikku-mw-http-names-', project, (state) => {
+        const group = state.http.routeMiddleware.get('*')!
+        const names = [
+          group.exportName,
+          ...(group.additionalRegistrations ?? []).map((r) => r.exportName),
+        ]
+        assert.deepEqual(names.sort(), [
+          'loggingMiddleware',
+          'sessionMiddleware',
+        ])
+      })
+    })
+
+    test('unions the services both registrations need', async () => {
+      await withProject('pikku-mw-http-services-', project, (state) => {
+        const group = state.http.routeMiddleware.get('*')!
+        assert.equal(
+          new Set(group.services.services).size,
+          group.services.services.length,
+          'services must not repeat when two groups merge'
+        )
+      })
+    })
+  })
+
+  test('a single registration is unchanged', async () => {
+    await withProject(
+      'pikku-mw-http-single-',
+      {
+        'session.ts': [
+          "import { addHTTPMiddleware, pikkuMiddleware } from '#pikku'",
+          'export const sessionMiddleware = () =>',
+          "  addHTTPMiddleware('*', [",
+          '    pikkuMiddleware(async (_s, _w, next) => next()),',
+          '  ])',
+        ],
+      },
+      (state) => {
+        const group = state.http.routeMiddleware.get('*')!
+        assert.equal(group.exportName, 'sessionMiddleware')
+        assert.equal(
+          group.additionalRegistrations,
+          undefined,
+          'nothing to merge means nothing extra to serialize'
+        )
+      }
+    )
+  })
+
+  test('different patterns stay separate groups', async () => {
+    await withProject(
+      'pikku-mw-http-distinct-',
+      {
+        'session.ts': [
+          "import { addHTTPMiddleware, pikkuMiddleware } from '#pikku'",
+          'export const sessionMiddleware = () =>',
+          "  addHTTPMiddleware('*', [",
+          '    pikkuMiddleware(async (_s, _w, next) => next()),',
+          '  ])',
+        ],
+        'api.ts': [
+          "import { addHTTPMiddleware, pikkuMiddleware } from '#pikku'",
+          'export const apiMiddleware = () =>',
+          "  addHTTPMiddleware('/api/*', [",
+          '    pikkuMiddleware(async (_s, _w, next) => next()),',
+          '  ])',
+        ],
+      },
+      (state) => {
+        assert.equal(sourceFiles(state.http.routeMiddleware.get('*')).length, 1)
+        assert.equal(
+          sourceFiles(state.http.routeMiddleware.get('/api/*')).length,
+          1
+        )
+      }
+    )
+  })
+
+  test('two files registering the same tag keep both registrations', async () => {
+    await withProject(
+      'pikku-mw-tag-collide-',
+      {
+        'session.ts': [
+          "import { addTagMiddleware, pikkuMiddleware } from '#pikku'",
+          'export const sessionTag = () =>',
+          "  addTagMiddleware('api', [",
+          '    pikkuMiddleware(async (_s, _w, next) => next()),',
+          '  ])',
+        ],
+        'logging.ts': [
+          "import { addTagMiddleware, pikkuMiddleware } from '#pikku'",
+          'export const loggingTag = () =>',
+          "  addTagMiddleware('api', [",
+          '    pikkuMiddleware(async (_s, _w, next) => next()),',
+          '  ])',
+        ],
+      },
+      (state) => {
+        assert.equal(
+          sourceFiles(state.middleware.tagMiddleware.get('api')).length,
+          2
+        )
+      }
+    )
+  })
+})

package/src/add/add-middleware.ts

@@ -1,5 +1,9 @@
 import * as ts from 'typescript'
-import type { AddWiring, InspectorState } from '../types.js'
+import type {
+  AddWiring,
+  InspectorState,
+  MiddlewareGroupMeta,
+} from '../types.js'
 import {
   extractFunctionName,
   isNamedExport,
@@ -13,6 +17,62 @@ import { extractMiddlewareRefs } from '../utils/middleware.js'
 import { getPropertyValue } from '../utils/get-property-value.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 
+/**
+ * Record a middleware group, keeping any registration already stored under the
+ * same pattern or tag.
+ *
+ * Several files may add middleware for one pattern — an app's own `'*'` group
+ * alongside the generated better-auth session bridge, say — and the runtime
+ * composes them. A plain `set` kept only the last, and codegen emits imports
+ * from what is stored, so the other file was never imported and its middleware
+ * silently stopped running. Merging is the only shape that cannot lose a gate;
+ * the first registration stays primary so single-registration groups serialize
+ * exactly as before.
+ */
+function recordMiddlewareGroup(
+  groups: Map<string, MiddlewareGroupMeta>,
+  key: string,
+  group: MiddlewareGroupMeta
+): void {
+  const existing = groups.get(key)
+  if (!existing) {
+    groups.set(key, group)
+    return
+  }
+
+  // The same call seen twice — the inspector may revisit a file — is not a
+  // second registration, and appending it would emit a duplicate import.
+  const alreadyRecorded = [
+    existing,
+    ...(existing.additionalRegistrations ?? []),
+  ]
+  if (
+    alreadyRecorded.some(
+      (r) => r.sourceFile === group.sourceFile && r.position === group.position
+    )
+  ) {
+    return
+  }
+
+  existing.additionalRegistrations = [
+    ...(existing.additionalRegistrations ?? []),
+    {
+      exportName: group.exportName,
+      sourceFile: group.sourceFile,
+      position: group.position,
+      isFactory: group.isFactory,
+    },
+  ]
+  existing.count += group.count
+  existing.instanceIds = [...existing.instanceIds, ...group.instanceIds]
+  existing.services = {
+    optimized: false,
+    services: Array.from(
+      new Set([...existing.services.services, ...group.services.services])
+    ),
+  }
+}
+
 function renameTempDefinitions(
   state: InspectorState,
   definitionIds: string[],
@@ -333,7 +393,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
       )
     }
 
-    state.middleware.tagMiddleware.set(tag, {
+    recordMiddlewareGroup(state.middleware.tagMiddleware, tag, {
       exportName: exportedName,
       sourceFile,
       position: node.getStart(),
@@ -477,7 +537,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
       )
     }
 
-    state.http.routeMiddleware.set(pattern, {
+    recordMiddlewareGroup(state.http.routeMiddleware, pattern, {
       exportName: exportedName,
       sourceFile,
       position: node.getStart(),
@@ -796,7 +856,7 @@ export const addMiddleware: AddWiring = (logger, node, checker, state) => {
       )
     }
 
-    state.channelMiddleware.tagMiddleware.set(tag, {
+    recordMiddlewareGroup(state.channelMiddleware.tagMiddleware, tag, {
       exportName: exportedName,
       sourceFile,
       position: node.getStart(),

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

@@ -0,0 +1,268 @@
+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-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 })
+  }
+}
+
+/** 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('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)
+  })
+
+  // 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, [])
+  })
+})