@pikku/inspector 0.12.74 → 0.12.81

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

@@ -1,419 +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 { 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-scope-'))
-  const file = join(rootDir, 'scopes.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-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 { defineScope } from '@pikku/core/scope'",
-        'defineScope({',
-        '  admin: {',
-        "    displayName: 'Administration',",
-        "    description: 'Administrative access',",
-        '  },',
-        '})',
-      ].join('\n')
-    )
-
-    assert.equal(criticals.length, 0)
-    assert.equal(state.scopes.definitions.length, 1)
-    assert.equal(state.scopes.definitions[0]!.name, 'admin')
-    assert.equal(state.scopes.definitions[0]!.displayName, 'Administration')
-    assert.equal(
-      state.scopes.definitions[0]!.description,
-      'Administrative access'
-    )
-  })
-
-  test('extracts a displayName at every depth', async () => {
-    const { state, criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'defineScope({',
-        '  admin: {',
-        "    displayName: 'Administration',",
-        '    scopes: {',
-        '      invoices: {',
-        "        displayName: 'Invoice Management',",
-        '        scopes: {',
-        "          create: { displayName: 'Create Invoices' },",
-        '        },',
-        '      },',
-        '    },',
-        '  },',
-        '})',
-      ].join('\n')
-    )
-
-    assert.equal(criticals.length, 0)
-    const admin = state.scopes.definitions[0]!
-    assert.equal(admin.displayName, 'Administration')
-    const invoices = admin.scopes!.invoices!
-    assert.equal(invoices.displayName, 'Invoice Management')
-    assert.equal(invoices.scopes!.create!.displayName, 'Create Invoices')
-  })
-
-  test('extracts a nested scope tree', async () => {
-    const { state, criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'defineScope({',
-        '  admin: {',
-        '    scopes: {',
-        '      invoices: {',
-        "        description: 'Invoice management',",
-        '        scopes: {',
-        "          create: { description: 'Create invoices' },",
-        '        },',
-        '      },',
-        '    },',
-        '  },',
-        '})',
-      ].join('\n')
-    )
-
-    assert.equal(criticals.length, 0)
-    assert.deepEqual(state.scopes.definitions[0]!.scopes, {
-      invoices: {
-        description: 'Invoice management',
-        scopes: {
-          create: { description: 'Create invoices' },
-        },
-      },
-    })
-  })
-
-  test('records the source file', async () => {
-    const { state, file } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'defineScope({ admin: {} })',
-      ].join('\n')
-    )
-
-    assert.equal(state.scopes.definitions[0]!.sourceFile, file)
-    assert.ok(state.scopes.files.has(file))
-  })
-
-  // The point of the keyed form: one call declares as many roots as you like,
-  // and a root reads exactly like the nodes beneath it.
-  test('extracts several roots from one declaration', async () => {
-    const { state, criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'defineScope({ admin: {}, billing: { scopes: { read: {} } } })',
-      ].join('\n')
-    )
-
-    assert.equal(criticals.length, 0)
-    assert.deepEqual(
-      state.scopes.definitions.map((d) => d.name),
-      ['admin', 'billing']
-    )
-    assert.deepEqual(state.scopes.definitions[1]!.scopes, { read: {} })
-  })
-
-  test('extracts several declarations', async () => {
-    const { state } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'defineScope({ admin: {} })',
-        'defineScope({ billing: {} })',
-      ].join('\n')
-    )
-
-    assert.deepEqual(
-      state.scopes.definitions.map((d) => d.name),
-      ['admin', 'billing']
-    )
-  })
-
-  // 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 { defineScope } from '@pikku/core/scope'",
-        "defineScope({ 'admin:users': {} })",
-      ].join('\n')
-    )
-
-    assert.ok(
-      criticals.some((c) => c.code === ErrorCode.INVALID_VALUE),
-      `expected an INVALID_VALUE critical, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('is critical when a root is the wildcard', async () => {
-    const { criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        "defineScope({ '*': {} })",
-      ].join('\n')
-    )
-
-    assert.ok(
-      criticals.some((c) => c.code === ErrorCode.INVALID_VALUE),
-      `expected an INVALID_VALUE critical, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('is critical when a root key is not a literal', async () => {
-    const { criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        'const k = String(1)',
-        'defineScope({ [k]: {} } as any)',
-      ].join('\n')
-    )
-
-    assert.ok(
-      criticals.some((c) => c.code === ErrorCode.NON_LITERAL_WIRE_NAME),
-      `expected a NON_LITERAL_WIRE_NAME critical, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('is critical when a root is not an object literal', async () => {
-    const { criticals } = await inspectSource(
-      [
-        "import { defineScope } from '@pikku/core/scope'",
-        "defineScope({ admin: 'nope' } as any)",
-      ].join('\n')
-    )
-
-    assert.ok(
-      criticals.some((c) => c.code === ErrorCode.INVALID_VALUE),
-      `expected an INVALID_VALUE critical, got ${JSON.stringify(criticals)}`
-    )
-  })
-})
-
-describe('validateScopeReferences', () => {
-  const funcSource = (scopes: string, decls: string[] = []) =>
-    [
-      "import { defineScope } from '@pikku/core/scope'",
-      "import { pikkuSessionlessFunc } from '@pikku/core'",
-      ...decls,
-      'export const f = pikkuSessionlessFunc({',
-      `  scopes: ${scopes},`,
-      "  func: async () => 'ok',",
-      '})',
-    ].join('\n')
-
-  test('accepts a declared scope', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['admin:invoices:create']", [
-        'defineScope({',
-        '  admin: {',
-        '    scopes: { invoices: { scopes: { create: {} } } },',
-        '  },',
-        '})',
-      ])
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-
-  test('accepts an intermediate node of a declared tree', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['admin:invoices']", [
-        'defineScope({',
-        '  admin: {',
-        '    scopes: { invoices: { scopes: { create: {} } } },',
-        '  },',
-        '})',
-      ])
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-
-  test('rejects an undeclared scope', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['billing:read']", ['defineScope({ admin: {} })'])
-    )
-
-    assert.ok(
-      criticals.some(
-        (c) =>
-          c.code === ErrorCode.INVALID_VALUE &&
-          c.message.includes('billing:read')
-      ),
-      `expected an INVALID_VALUE critical for billing:read, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('lists the available scopes when one is undeclared', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['nope']", ['defineScope({ admin: {} })'])
-    )
-
-    assert.ok(
-      criticals.some((c) => c.message.includes('Available scopes: admin')),
-      `expected the message to list available scopes, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('rejects a typo in a nested scope', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['admin:invoice:create']", [
-        'defineScope({',
-        '  admin: {',
-        '    scopes: { invoices: { scopes: { create: {} } } },',
-        '  },',
-        '})',
-      ])
-    )
-
-    assert.ok(
-      criticals.some((c) => c.message.includes('admin:invoice:create')),
-      `expected a critical for the typo, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('accepts a wildcard requirement whose node is declared', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['admin:*']", ['defineScope({ admin: {} })'])
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-
-  test('rejects a wildcard requirement whose node is undeclared', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['billing:*']", ['defineScope({ admin: {} })'])
-    )
-
-    assert.ok(
-      criticals.some((c) => c.message.includes('billing:*')),
-      `expected a critical for billing:*, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('rejects a bare wildcard requirement', async () => {
-    const { criticals } = await inspectSource(
-      funcSource("['*']", ['defineScope({ admin: {} })'])
-    )
-
-    assert.ok(
-      criticals.some((c) => c.message.includes('bare wildcard')),
-      `expected a critical for the bare wildcard, got ${JSON.stringify(criticals)}`
-    )
-  })
-
-  test('is silent for a function declaring no scopes', async () => {
-    const { criticals } = await inspectSource(
-      [
-        "import { pikkuSessionlessFunc } from '@pikku/core'",
-        "export const f = pikkuSessionlessFunc({ func: async () => 'ok' })",
-      ].join('\n')
-    )
-
-    assert.deepEqual(criticals, [])
-  })
-})

package/src/add/add-scope.ts

@@ -1,221 +0,0 @@
-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/scope'
-
-const SEPARATOR = ':'
-const WILDCARD = '*'
-
-/**
- * Validates a single scope segment, reporting rather than throwing so the
- * inspector can surface every problem in one pass.
- *
- * @returns true when the segment is usable.
- */
-const isValidSegment = (
-  segment: string,
-  scopeName: string,
-  logger: InspectorLogger
-): boolean => {
-  if (segment.length === 0) {
-    logger.critical(
-      ErrorCode.INVALID_VALUE,
-      `Scope '${scopeName}' contains an empty segment.`
-    )
-    return false
-  }
-  if (segment.includes(SEPARATOR)) {
-    logger.critical(
-      ErrorCode.INVALID_VALUE,
-      `Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
-        `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`
-    )
-    return false
-  }
-  if (segment === WILDCARD) {
-    logger.critical(
-      ErrorCode.INVALID_VALUE,
-      `Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
-        `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`
-    )
-    return false
-  }
-  return true
-}
-
-/**
- * Recursively extracts a `scopes: { ... }` object literal into nested metadata.
- */
-const extractScopeNodes = (
-  obj: ts.ObjectLiteralExpression,
-  scopeName: string,
-  logger: InspectorLogger
-): Record<string, ScopeNodeMeta> | undefined => {
-  const nodes: Record<string, ScopeNodeMeta> = {}
-
-  for (const prop of obj.properties) {
-    if (!ts.isPropertyAssignment(prop)) {
-      continue
-    }
-
-    let segment: string | undefined
-    if (ts.isIdentifier(prop.name)) {
-      segment = prop.name.text
-    } else if (ts.isStringLiteral(prop.name)) {
-      segment = prop.name.text
-    }
-
-    if (segment === undefined) {
-      logger.critical(
-        ErrorCode.NON_LITERAL_WIRE_NAME,
-        `Scope '${scopeName}' has a nested scope whose key is not a literal.`
-      )
-      continue
-    }
-
-    if (!isValidSegment(segment, scopeName, logger)) {
-      continue
-    }
-
-    if (!ts.isObjectLiteralExpression(prop.initializer)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `Nested scope '${segment}' in '${scopeName}' must be an object literal.`
-      )
-      continue
-    }
-
-    const node: ScopeNodeMeta = {}
-    const displayName = getPropertyValue(prop.initializer, 'displayName') as
-      string | null
-    if (displayName) {
-      node.displayName = displayName
-    }
-    const description = getPropertyValue(prop.initializer, 'description') as
-      string | null
-    if (description) {
-      node.description = description
-    }
-
-    const nestedProp = prop.initializer.properties.find(
-      (p) =>
-        ts.isPropertyAssignment(p) &&
-        ts.isIdentifier(p.name) &&
-        p.name.text === 'scopes'
-    )
-    if (
-      nestedProp &&
-      ts.isPropertyAssignment(nestedProp) &&
-      ts.isObjectLiteralExpression(nestedProp.initializer)
-    ) {
-      const nested = extractScopeNodes(
-        nestedProp.initializer,
-        scopeName,
-        logger
-      )
-      if (nested) {
-        node.scopes = nested
-      }
-    }
-
-    nodes[segment] = node
-  }
-
-  return Object.keys(nodes).length > 0 ? nodes : undefined
-}
-
-/**
- * Unwraps `x as const` / `x as any` 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
-
-export const addScope: AddWiring = (logger, node, checker, state, _options) => {
-  if (!ts.isCallExpression(node)) {
-    return
-  }
-
-  const expression = node.expression
-  if (!ts.isIdentifier(expression) || expression.text !== 'defineScope') {
-    return
-  }
-
-  const firstArg = node.arguments[0]
-  if (!firstArg) {
-    return
-  }
-
-  const unwrapped = unwrapAs(firstArg)
-  if (!ts.isObjectLiteralExpression(unwrapped)) {
-    return
-  }
-
-  const sourceFile = node.getSourceFile().fileName
-
-  // Roots are keyed exactly like the nodes beneath them, so each property of
-  // the call's single argument is one tree.
-  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 scope is declared with a key that is not a literal.'
-      )
-      continue
-    }
-
-    if (!isValidSegment(name, name, logger)) {
-      continue
-    }
-
-    if (!ts.isObjectLiteralExpression(prop.initializer)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `Scope '${name}' must be an object literal.`
-      )
-      continue
-    }
-
-    const root = prop.initializer
-    const displayNameValue = getPropertyValue(root, 'displayName') as
-      string | null
-    const descriptionValue = getPropertyValue(root, 'description') as
-      string | null
-
-    let scopes: Record<string, ScopeNodeMeta> | undefined
-    const scopesProp = root.properties.find(
-      (p) =>
-        ts.isPropertyAssignment(p) &&
-        ts.isIdentifier(p.name) &&
-        p.name.text === 'scopes'
-    )
-    if (
-      scopesProp &&
-      ts.isPropertyAssignment(scopesProp) &&
-      ts.isObjectLiteralExpression(scopesProp.initializer)
-    ) {
-      scopes = extractScopeNodes(scopesProp.initializer, name, logger)
-    }
-
-    state.scopes.files.add(sourceFile)
-    state.scopes.definitions.push({
-      name,
-      displayName: displayNameValue || undefined,
-      description: descriptionValue || undefined,
-      scopes,
-      sourceFile,
-    })
-  }
-}

package/src/add/add-secret.ts

@@ -1,10 +0,0 @@
-import { createAddKeyedWiring } from './add-keyed-wiring.js'
-
-export const addSecret = createAddKeyedWiring({
-  functionName: 'defineSecret',
-  idField: 'secretId',
-  label: 'Secret',
-  schemaPrefix: 'SecretSchema',
-  flagField: 'optional',
-  getState: (state) => state.secrets,
-})