@pikku/inspector 0.12.59 → 0.12.61

package/src/utils/annotate-http-route-auth.test.ts

@@ -108,18 +108,16 @@ describe('annotateHttpRouteAuth', () => {
 
   test('a ref route resolves against its target', () => {
     const state = {
-      functions: {
-        meta: {
-          inline: { pikkuFuncId: 'inline', sessionless: true },
-          target: { pikkuFuncId: 'target', sessionless: false },
-        },
+      functions: { meta: {} },
+      addonFunctions: {
+        console: { target: { pikkuFuncId: 'target', sessionless: false } },
       },
       http: {
         meta: {
           get: {
             '/thing': {
-              pikkuFuncId: 'inline',
-              refTarget: 'target',
+              pikkuFuncId: 'console:target',
+              packageName: ADDON_PACKAGE,
               route: '/thing',
               method: 'get',
             },

package/src/utils/annotate-http-route-auth.ts

@@ -1,4 +1,5 @@
 import type { InspectorState } from '../types.js'
+import { resolveFunctionMeta } from './resolve-function-meta.js'
 
 /**
  * Resolve, per HTTP route, whether reaching it requires a session.
@@ -25,7 +26,7 @@ export function annotateHttpRouteAuth(state: InspectorState): void {
 
   for (const routes of Object.values(state.http?.meta ?? {})) {
     for (const route of Object.values(routes)) {
-      const meta = state.functions.meta[route.refTarget ?? route.pikkuFuncId]
+      const meta = resolveFunctionMeta(state, route.pikkuFuncId)
 
       route.requiresSession =
         // A pikkuFunc always requires a session, on every path.

package/src/utils/check-secret-sinks.ts

@@ -53,7 +53,10 @@ export function findRevealedSecretSinks(
   const violations: SecretSinkViolation[] = []
 
   const visit = (node: ts.Node): void => {
-    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression)
+    ) {
       const sink = describeSink(checker, node.expression)
       if (sink) {
         for (const arg of node.arguments) {

package/src/utils/compute-required-schemas.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
 import type { TypesMap } from '../types-map.js'
 import type { SchemaRef } from '../types.js'
 

package/src/utils/contract-hashes.test.ts

@@ -10,7 +10,7 @@ import {
   extractContractsFromMeta,
 } from './contract-hashes.js'
 import type { ContractEntry, VersionManifest } from './contract-hashes.js'
-import type { FunctionsMeta } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
 import { ErrorCode } from '../error-codes.js'
 
 function makeContracts(

package/src/utils/contract-hashes.ts

@@ -1,5 +1,6 @@
-import type { FunctionsMeta, JSONValue } from '@pikku/core'
-import { parseVersionedId } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
+import type { JSONValue } from '@pikku/core/utils'
+import { parseVersionedId } from '@pikku/core/utils'
 import type { TypesMap } from '../types-map.js'
 import { ErrorCode } from '../error-codes.js'
 import { canonicalJSON, hashString } from './hash.js'

package/src/utils/extract-function-name.ts

@@ -1,7 +1,7 @@
 import * as ts from 'typescript'
 import { createHash } from 'crypto'
 import { relative } from 'path'
-import { formatVersionedId } from '@pikku/core'
+import { formatVersionedId } from '@pikku/core/utils'
 
 /**
  * Deterministic placeholder id for an anonymous/unnamed pikku function or

package/src/utils/extract-services.ts

@@ -1,6 +1,8 @@
 import * as ts from 'typescript'
-import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core'
-
+import type {
+  FunctionServicesMeta,
+  FunctionWiresMeta,
+} from '@pikku/core/function'
 /**
  * Extract services from a function's first parameter destructuring pattern
  */

package/src/utils/extract-surface-usage.test.ts

@@ -0,0 +1,147 @@
+import assert from 'node:assert'
+import { describe, test } from 'node:test'
+import ts from 'typescript'
+
+import {
+  accumulateSurfaceUsage,
+  surfaceUsageArea,
+  type SurfaceUsageCounts,
+} from './extract-surface-usage.js'
+
+const countsFor = (
+  files: Array<{ area: string; source: string }>
+): SurfaceUsageCounts => {
+  const counts: SurfaceUsageCounts = {}
+  files.forEach(({ area, source }, index) => {
+    const file = `src/file-${index}.ts`
+    accumulateSurfaceUsage(
+      ts.createSourceFile(
+        `/project/${file}`,
+        source,
+        ts.ScriptTarget.Latest,
+        true
+      ),
+      { area, file },
+      counts
+    )
+  })
+  return counts
+}
+
+describe('accumulateSurfaceUsage', () => {
+  test('counts an import site per named import', () => {
+    const counts = countsFor([
+      {
+        area: 'src',
+        source:
+          "import { pikkuFunc, pikkuSessionlessFunc } from '#pikku/function'\n",
+      },
+      { area: 'src', source: "import { pikkuFunc } from '#pikku/function'\n" },
+    ])
+
+    assert.deepStrictEqual(counts['#pikku/function'], {
+      pikkuFunc: {
+        imports: 2,
+        seenIn: ['src'],
+        files: ['src/file-0.ts', 'src/file-1.ts'],
+      },
+      pikkuSessionlessFunc: {
+        imports: 1,
+        seenIn: ['src'],
+        files: ['src/file-0.ts'],
+      },
+    })
+  })
+
+  test('counts a deep specifier against the leaf it belongs to', () => {
+    const counts = countsFor([
+      {
+        area: 'src',
+        source:
+          "import { pikkuWorkflowFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'\n",
+      },
+      {
+        area: 'workers',
+        source: "import { pikkuWorkflowFunc } from '#pikku/workflow'\n",
+      },
+    ])
+
+    assert.deepStrictEqual(counts['#pikku/workflow'], {
+      pikkuWorkflowFunc: {
+        imports: 2,
+        seenIn: ['src', 'workers'],
+        files: ['src/file-0.ts', 'src/file-1.ts'],
+      },
+    })
+  })
+
+  test('records the aliased name, not the local one', () => {
+    const counts = countsFor([
+      {
+        area: 'src',
+        source: "import { cors as allowAll } from '#pikku/http'\n",
+      },
+    ])
+
+    assert.deepStrictEqual(counts['#pikku/http'], {
+      cors: { imports: 1, seenIn: ['src'], files: ['src/file-0.ts'] },
+    })
+  })
+
+  test('counts a re-export as a use of the leaf', () => {
+    const counts = countsFor([
+      { area: 'src', source: "export { wireHTTP } from '#pikku/http'\n" },
+    ])
+
+    assert.deepStrictEqual(counts['#pikku/http']!.wireHTTP!.imports, 1)
+  })
+
+  test('ignores imports from anywhere else', () => {
+    const counts = countsFor([
+      {
+        area: 'src',
+        source: [
+          "import { z } from 'zod'",
+          "import { thing } from './local.js'",
+          "import * as everything from '#pikku/function'",
+          "import bootstrap from '#pikku/pikku-bootstrap.gen.js'",
+        ].join('\n'),
+      },
+    ])
+
+    assert.deepStrictEqual(counts, {})
+  })
+})
+
+describe('surfaceUsageArea', () => {
+  test('falls back to the top-level source directory in a single package', () => {
+    assert.strictEqual(
+      surfaceUsageArea('/project/src/wirings/todo.ts', '/project', new Map()),
+      'src'
+    )
+  })
+
+  test('does not label everything with the root package name', () => {
+    const cache = new Map<string, string | null>([
+      ['/project/src/wirings', null],
+      ['/project/src', null],
+    ])
+
+    assert.strictEqual(
+      surfaceUsageArea('/project/src/wirings/todo.ts', '/project', cache),
+      'src'
+    )
+  })
+
+  test('prefers the workspace package a file belongs to', () => {
+    const cache = new Map<string, string | null>([
+      ['/project/packages/api/src', null],
+      ['/project/packages/api', '@app/api'],
+    ])
+
+    assert.strictEqual(
+      surfaceUsageArea('/project/packages/api/src/todo.ts', '/project', cache),
+      '@app/api'
+    )
+  })
+})

package/src/utils/extract-surface-usage.ts

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from 'fs'
+import { basename, dirname, relative, sep } from 'path'
+import ts from 'typescript'
+
+/**
+ * How often each `#pikku/*` export is imported, the source areas it was
+ * imported from, and the files those imports are written in. Counters only:
+ * this is accumulated during the sweep that already visits every source file,
+ * so nothing here may retain a node.
+ */
+export type SurfaceUsageCounts = Record<
+  string,
+  Record<string, { imports: number; seenIn: string[]; files: string[] }>
+>
+
+/**
+ * The leaf a specifier belongs to. `#pikku/workflow` and the deep
+ * `#pikku/workflow/pikku-workflow-types.gen.js` are the same door, so both
+ * count against `#pikku/workflow`.
+ */
+const leafSpecifierOf = (specifier: string): string | null => {
+  if (!specifier.startsWith('#pikku/')) return null
+  const leaf = specifier.slice('#pikku/'.length).split('/')[0]
+  // A root-level generated file, e.g. `#pikku/pikku-bootstrap.gen.js`, is not a
+  // leaf and has no editorial entry to count against.
+  if (!leaf || leaf.endsWith('.js')) return null
+  return `#pikku/${leaf}`
+}
+
+const packageNameAt = (
+  directory: string,
+  cache: Map<string, string | null>
+): string | null => {
+  const cached = cache.get(directory)
+  if (cached !== undefined) return cached
+  let name: string | null = null
+  const path = `${directory}${sep}package.json`
+  if (existsSync(path)) {
+    try {
+      name =
+        (JSON.parse(readFileSync(path, 'utf8')) as { name?: string }).name ??
+        null
+    } catch {
+      name = null
+    }
+  }
+  cache.set(directory, name)
+  return name
+}
+
+/**
+ * A label a person recognises: the workspace package a file belongs to, or the
+ * top-level source directory it sits under when the project is one package.
+ * The root package is skipped deliberately — naming it would label every file
+ * in a single-package project identically.
+ */
+export const surfaceUsageArea = (
+  fileName: string,
+  rootDir: string,
+  cache: Map<string, string | null>
+): string => {
+  let directory = dirname(fileName)
+  while (directory.startsWith(rootDir) && directory !== rootDir) {
+    const name = packageNameAt(directory, cache)
+    if (name) return name
+    directory = dirname(directory)
+  }
+  const [segment] = relative(rootDir, fileName).split(sep)
+  return segment && segment !== basename(fileName) ? segment : basename(rootDir)
+}
+
+const namesOf = (
+  clause: ts.NamedImportBindings | ts.NamedExportBindings | undefined
+): string[] => {
+  if (!clause) return []
+  if (ts.isNamedImports(clause) || ts.isNamedExports(clause)) {
+    return clause.elements.map(
+      (element) => (element.propertyName ?? element.name).text
+    )
+  }
+  return []
+}
+
+/**
+ * Counts the `#pikku/*` imports of one file into `into`. Only the file's own
+ * top-level statements are looked at — an import declaration can appear nowhere
+ * else — so this costs a single pass over the statement list and retains
+ * nothing.
+ */
+export const accumulateSurfaceUsage = (
+  sourceFile: ts.SourceFile,
+  { area, file }: { area: string; file: string },
+  into: SurfaceUsageCounts
+): void => {
+  for (const statement of sourceFile.statements) {
+    let specifier: ts.Expression | undefined
+    let names: string[] = []
+
+    if (ts.isImportDeclaration(statement)) {
+      specifier = statement.moduleSpecifier
+      names = namesOf(statement.importClause?.namedBindings)
+    } else if (ts.isExportDeclaration(statement) && statement.moduleSpecifier) {
+      specifier = statement.moduleSpecifier
+      names = namesOf(statement.exportClause)
+    }
+
+    if (!specifier || names.length === 0 || !ts.isStringLiteral(specifier)) {
+      continue
+    }
+    const leaf = leafSpecifierOf(specifier.text)
+    if (!leaf) continue
+
+    const symbols = (into[leaf] ??= {})
+    for (const name of names) {
+      const usage = (symbols[name] ??= { imports: 0, seenIn: [], files: [] })
+      usage.imports += 1
+      if (!usage.seenIn.includes(area)) usage.seenIn.push(area)
+      if (!usage.files.includes(file)) usage.files.push(file)
+    }
+  }
+}

package/src/utils/filter-inspector-state.test.ts

@@ -1614,6 +1614,54 @@ describe('addonServerlessIncompatible scoping', () => {
   })
 })
 
+describe("an addon's own deploy conflict is the consumer's only when used", () => {
+  // An addon publishes metadata for everything it exports. A function it marks
+  // `deploy: 'serverless'` while also naming one of its services
+  // serverless-incompatible is the addon author's contradiction — but the
+  // deploy scan walks every published function, so without care it fails the
+  // build of a consumer that never wires that function.
+  const withConflictingAddonFunction = (route?: string) => {
+    const state = createMockInspectorState()
+    ;(state as any).addonFunctions = {
+      ffmpeg: {
+        transcode: {
+          deploy: 'serverless',
+          services: { services: ['FfmpegService'] },
+        },
+      },
+    }
+    state.addonServerlessIncompatible = new Map([['ffmpeg', ['FfmpegService']]])
+    if (route) {
+      ;(state.http.meta.get as any)[route] = {
+        pikkuFuncId: 'ffmpeg:transcode',
+        route,
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      }
+    }
+    return state
+  }
+
+  test('a conflicting addon function nothing wires does not fail the build', () => {
+    const state = withConflictingAddonFunction()
+
+    assert.doesNotThrow(() =>
+      filterInspectorState(state, { target: ['serverless'] }, mockLogger)
+    )
+  })
+
+  test('wiring that same function reports the conflict', () => {
+    const state = withConflictingAddonFunction('/transcode')
+
+    assert.throws(
+      () => filterInspectorState(state, { target: ['serverless'] }, mockLogger),
+      /FfmpegService/
+    )
+  })
+})
+
 describe('addonServerlessIncompatible serialization roundtrip', () => {
   // Uses getInitialInspectorState to guarantee all Map fields are initialized —
   // the lightweight mock in createMockInspectorState() omits fields like
@@ -1705,21 +1753,18 @@ describe('addon bootstrap tree-shake', () => {
   test('keeps an addon when a kept route ref()-targets one of its functions', () => {
     const state = withAddon((s) => {
       s.http.meta.get['/workflow-run/stream'] = {
-        pikkuFuncId: 'http:get:/workflow-run/stream',
-        refTarget: 'console:streamWorkflowRun',
+        pikkuFuncId: 'console:streamWorkflowRun',
+        packageName: '@pikku/console',
         route: '/workflow-run/stream',
         method: 'GET',
-        tags: [],
+        tags: ['stream'],
         middleware: [],
         permissions: [],
       } as any
-      s.functions.meta['http:get:/workflow-run/stream'] = {
-        services: { optimized: false, services: [] },
-      } as any
     })
     const filtered = filterInspectorState(
       state,
-      { names: ['http:get:/workflow-run/stream'] },
+      { tags: ['stream'] },
       mockLogger
     )
     assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
@@ -1729,19 +1774,41 @@ describe('addon bootstrap tree-shake', () => {
     )
   })
 
-  test('drops the addon when the ref()-wired route is filtered out', () => {
+  test('keeps a ref()-wired route selected by its wiring id', () => {
     const state = withAddon((s) => {
       s.http.meta.get['/workflow-run/stream'] = {
-        pikkuFuncId: 'http:get:/workflow-run/stream',
-        refTarget: 'console:streamWorkflowRun',
+        pikkuFuncId: 'console:streamWorkflowRun',
+        packageName: '@pikku/console',
         route: '/workflow-run/stream',
         method: 'GET',
         tags: [],
         middleware: [],
         permissions: [],
       } as any
-      s.functions.meta['http:get:/workflow-run/stream'] = {
-        services: { optimized: false, services: [] },
+    })
+    const filtered = filterInspectorState(
+      state,
+      { names: ['http:get:/workflow-run/stream'] },
+      mockLogger
+    )
+    assert.ok(filtered.http.meta.get['/workflow-run/stream'])
+    assert.ok(
+      filtered.serviceAggregation.usedFunctions.has('console:streamWorkflowRun')
+    )
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+    assert.ok(filtered.rpc.wireAddonDeclarations.has('console'))
+  })
+
+  test('drops the addon when the ref()-wired route is filtered out', () => {
+    const state = withAddon((s) => {
+      s.http.meta.get['/workflow-run/stream'] = {
+        pikkuFuncId: 'console:streamWorkflowRun',
+        packageName: '@pikku/console',
+        route: '/workflow-run/stream',
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
       } as any
     })
     const filtered = filterInspectorState(
@@ -1843,6 +1910,65 @@ describe('addon bootstrap tree-shake', () => {
     const filtered = filterInspectorState(state, {}, mockLogger)
     assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
   })
+
+  const withRefWiredAddonRoute = (
+    addonFuncMeta: Record<string, unknown> = { services: [], optimized: false }
+  ) =>
+    withAddon((s) => {
+      s.http.meta.get['/workflow-run/stream'] = {
+        pikkuFuncId: 'console:streamWorkflowRun',
+        packageName: '@pikku/addon-console',
+        route: '/workflow-run/stream',
+        method: 'GET',
+        tags: [],
+        middleware: [],
+        permissions: [],
+      } as any
+      s.addonFunctions = {
+        console: { streamWorkflowRun: addonFuncMeta as any },
+      }
+    })
+
+  test('the deploy filter keeps a ref()-wired route onto a serverless addon function', () => {
+    const filtered = filterInspectorState(
+      withRefWiredAddonRoute(),
+      { target: ['serverless'] },
+      mockLogger
+    )
+    assert.ok(filtered.http.meta.get['/workflow-run/stream'])
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 1)
+    assert.ok(filtered.rpc.wireAddonDeclarations.has('console'))
+  })
+
+  test('the deploy filter drops a ref()-wired route onto a server-only addon function', () => {
+    const filtered = filterInspectorState(
+      withRefWiredAddonRoute({
+        services: [],
+        optimized: false,
+        deploy: 'server',
+      }),
+      { target: ['serverless'] },
+      mockLogger
+    )
+    assert.ok(!filtered.http.meta.get['/workflow-run/stream'])
+    assert.strictEqual(filtered.rpc.wireAddonDeclarations.size, 0)
+  })
+
+  test("the deploy filter honours the addon's own serverlessIncompatible services", () => {
+    const state = withRefWiredAddonRoute({
+      services: { services: ['FfmpegService'] },
+      optimized: false,
+    })
+    state.addonServerlessIncompatible = new Map([
+      ['console', ['FfmpegService']],
+    ])
+    const filtered = filterInspectorState(
+      state,
+      { target: ['serverless'] },
+      mockLogger
+    )
+    assert.ok(!filtered.http.meta.get['/workflow-run/stream'])
+  })
 })
 
 describe('invokedFunctionsByFile serialization', () => {