@pikku/inspector 0.12.60 → 0.12.61

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', () => {

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

@@ -3,10 +3,23 @@ import type {
   InspectorFilters,
   InspectorLogger,
 } from '../types.js'
-import type { PikkuWiringTypes } from '@pikku/core/ecosystem/types'
-import { parseVersionedId } from '@pikku/core/ecosystem/types'
+import type { PikkuWiringTypes } from '@pikku/core/types'
+import { parseVersionedId } from '@pikku/core/utils'
+import { makeContextBasedId } from './extract-function-name.js'
 import { aggregateRequiredServices } from './post-process.js'
-import { resolveDeployTarget } from './resolve-deploy-target.js'
+import {
+  IncompatibleDeployTargetError,
+  resolveDeployTarget,
+} from './resolve-deploy-target.js'
+
+/**
+ * The deploy filter, asked about one function at a time rather than handed over
+ * as a set, so that a function's own deploy conflict is raised only if this app
+ * turns out to wire it.
+ */
+type DeployFilter = {
+  has(pikkuFuncId: string): boolean
+}
 
 // Module-level Set to track warned groups across multiple filter calls
 const globalWarnedGroups = new Set<string>()
@@ -97,6 +110,13 @@ function matchesFilters(
   meta: {
     type: PikkuWiringTypes
     name: string
+    /**
+     * Further ids the `--names` filter may address this wiring by. An HTTP
+     * route wired with `ref('ns:fn')` carries the addon's own function id as
+     * its name, so its `http:<method>:<route>` wiring id is the only id that
+     * names this route rather than every wiring onto that addon function.
+     */
+    altNames?: string[]
     tags?: string[]
     filePath?: string
     httpRoute?: string
@@ -105,9 +125,10 @@ function matchesFilters(
   },
   logger: InspectorLogger,
   warnedGroups?: Set<string>,
-  // Set of pikkuFuncIds to keep based on the deploy filter; null when
-  // the deploy filter is inactive.
-  keptByDeploy?: Set<string> | null
+  // Kept pikkuFuncIds under the deploy filter; null when the filter is
+  // inactive. Asked about one id at a time, which is what lets a conflict in an
+  // addon's own metadata surface only for a function this app actually wires.
+  keptByDeploy?: DeployFilter | null
 ): boolean {
   // If no filters, allow everything
   if (Object.keys(filters).length === 0) return true
@@ -188,10 +209,15 @@ function matchesFilters(
     }
   }
 
-  const { baseName } = parseVersionedId(meta.name)
+  const candidateNames = [meta.name, ...(meta.altNames ?? [])]
   const matchesNamePattern = (pattern: string) =>
-    matchesWildcard(meta.name, pattern) ||
-    (baseName !== meta.name && matchesWildcard(baseName, pattern))
+    candidateNames.some((candidate) => {
+      const { baseName } = parseVersionedId(candidate)
+      return (
+        matchesWildcard(candidate, pattern) ||
+        (baseName !== candidate && matchesWildcard(baseName, pattern))
+      )
+    })
 
   // Check name include filter (match against both full ID and base name for versioned functions)
   if (filters.names && filters.names.length > 0) {
@@ -330,7 +356,7 @@ export function filterInspectorState(
   // Precompute kept-function set for the deploy filter (if active).
   // resolveDeployTarget throws IncompatibleDeployTargetError when an
   // explicit deploy: 'serverless' clashes with serverlessIncompatible.
-  let keptByDeploy: Set<string> | null = null
+  let keptByDeploy: DeployFilter | null = null
   if (
     (filters.target && filters.target.length > 0) ||
     (filters.excludeTarget && filters.excludeTarget.length > 0)
@@ -341,17 +367,56 @@ export function filterInspectorState(
       : null
     const incompatible = new Set(filters.serverlessIncompatible ?? [])
     const defaultTarget = filters.defaultTarget ?? 'serverless'
-    keptByDeploy = new Set<string>()
-    for (const [funcId, funcMeta] of Object.entries(state.functions.meta)) {
+    const kept = new Set<string>()
+    // An addon publishes metadata for everything it exports, so a conflict in a
+    // function this app never wires is not this app's build error. Holding it
+    // here and raising it from `has` reports it at the one place the app is
+    // known to depend on that function.
+    const conflicts = new Map<string, IncompatibleDeployTargetError>()
+    keptByDeploy = {
+      has: (funcId: string) => {
+        const conflict = conflicts.get(funcId)
+        if (conflict) throw conflict
+        return kept.has(funcId)
+      },
+    }
+    const keepByTarget = (
+      funcId: string,
+      funcMeta: unknown,
+      incompatibleServices: Set<string>
+    ) => {
       const target = resolveDeployTarget(
         funcMeta as any,
-        incompatible,
+        incompatibleServices,
         funcId,
         defaultTarget
       )
-      if (allowed && !allowed.has(target)) continue
-      if (excluded && excluded.has(target)) continue
-      keptByDeploy.add(funcId)
+      if (allowed && !allowed.has(target)) return
+      if (excluded && excluded.has(target)) return
+      kept.add(funcId)
+    }
+    for (const [funcId, funcMeta] of Object.entries(state.functions.meta)) {
+      keepByTarget(funcId, funcMeta, incompatible)
+    }
+    // A wiring onto an addon function records the addon's own id, so the
+    // addon's published metadata is the only place its deploy target can be
+    // read from. Its serverlessIncompatible services are namespace-scoped —
+    // a service name means whatever the addon that declared it means.
+    for (const [namespace, addonMeta] of Object.entries(
+      state.addonFunctions ?? {}
+    )) {
+      const addonIncompatible = new Set(
+        state.addonServerlessIncompatible?.get(namespace) ?? []
+      )
+      for (const [funcName, funcMeta] of Object.entries(addonMeta)) {
+        const funcId = `${namespace}:${funcName}`
+        try {
+          keepByTarget(funcId, funcMeta, addonIncompatible)
+        } catch (e) {
+          if (!(e instanceof IncompatibleDeployTargetError)) throw e
+          conflicts.set(funcId, e)
+        }
+      }
     }
   }
 
@@ -459,6 +524,7 @@ export function filterInspectorState(
         {
           type: 'http' as PikkuWiringTypes,
           name: routeMeta.pikkuFuncId, // Use function name, not route
+          altNames: [makeContextBasedId('http', method, routeMeta.route)],
           tags: routeMeta.tags,
           filePath,
           httpRoute: routeMeta.route,
@@ -478,11 +544,6 @@ export function filterInspectorState(
           filteredState.serviceAggregation.usedFunctions.add(
             routeMeta.pikkuFuncId
           )
-          if (routeMeta.refTarget) {
-            filteredState.serviceAggregation.usedFunctions.add(
-              routeMeta.refTarget
-            )
-          }
           // For workflow/agent routes, also add the base name
           // so the workflow/agent definition survives pruning
           const colonIdx = routeMeta.pikkuFuncId.indexOf(':')

package/src/utils/filter-utils.ts

@@ -1,5 +1,5 @@
 import type { InspectorFilters, InspectorLogger } from '../types.js'
-import type { PikkuWiringTypes } from '@pikku/core/ecosystem/types'
+import type { PikkuWiringTypes } from '@pikku/core/types'
 
 /**
  * Match a value against a pattern with wildcard support