@pikku/inspector 0.12.65 → 0.12.67

package/CHANGELOG.md

@@ -1,3 +1,76 @@
+## 0.12.67
+
+### Patch Changes
+
+- af2b764: **Breaking:** extend the classification sink scan to personal data, as PKU954.
+  A project that passes `pikku all --security --fail-on-error` today can fail
+  after upgrading, without a line of its own code changing.
+
+  PKU953 already followed a revealed vault secret into a logger, a queue, an
+  email, an audit or a webhook. A PII column reaches those same sinks with no
+  `.reveal()` to mark the moment — `Pii<T>` is simply the brand the generated row
+  types carry — and nothing flagged it.
+
+  It is not the same rule, because PII is not a secret: the question is not
+  whether the value is written down, but whether writing it there hands it to
+  somebody else. A log is shipped to a third-party aggregator and retained long
+  past any consent, and a webhook posts to another server, so both are reported.
+  An email is addressed to the data subject, an audit is a row in the operator's
+  own database, and a queue payload is consumed by the operator's own worker, so
+  none of those are. `private` is never reported at all — it says who may read
+  the row, not that recording it is a disclosure.
+
+  The scan is still opt-in behind `pikku all --security` and still reports at
+  `error` severity, so the dev server keeps starting and `--fail-on-error` is
+  what blocks a build. Where a finding is wrong, an explicit type annotation
+  erases the brand (`const email: string = shopper.email`) — but the better fix
+  is usually to correct the column's classification in `db/annotations.ts`.
+
+  Also fixes a false positive in the existing PKU953 scan: property-access
+  receivers were typed on the way down, and a row type is branded wherever any of
+  its columns are, so `user.userId` reported the row's `email`.
+
+- Updated dependencies [8154b1c]
+- Updated dependencies [6d9c09c]
+- Updated dependencies [239332b]
+  - @pikku/core@0.12.97
+
+## 0.12.66
+
+### Patch Changes
+
+- 2f94a0a: Stop `pikku all` failing on a diagnostic its own codegen went on to fix.
+
+  The run inspects several times, because generating the scaffold, the leaf indexes and the type files each changes the source graph the next inspection reads. Every full inspection re-runs every validator, so the newest pass is the complete one — but the logger accumulated diagnostics across all of them, and the build gate failed the run if any pass had ever recorded a critical.
+
+  A project whose system roles grant a scaffold-declared scope (`virtualUser:*`) therefore could not build from clean: the pass taken before the scaffold existed raised PKU124, the pass taken after was clean, and the run failed anyway. Same for PKU951 on a scaffold-declared secret.
+
+  Validation diagnostics are now scoped to the pass that recorded them, so a later pass supersedes an earlier one. Diagnostics reported outside a validation pass — by a generator or a command — are untouched, and a fault every pass reports still fails the run.
+
+- 7eeff81: Record `rpc!.invoke(...)` as an invocation
+
+  `rpc` is optional on the wire, so a caller that knows it is there writes
+  `rpc!.invoke('someFunction', …)`. The inspector matched the receiver as a bare
+  identifier, but a non-null assertion is a node of its own wrapping that
+  identifier, so those call sites were never recorded.
+
+  That is silent rather than loud. An invocation is what puts a function that is
+  not `expose: true` into the runtime registry, so the target was left
+  unregistered and the dispatch failed with `Function not found` — at run time,
+  on a call site that type-checked.
+
+  The generated virtual-user scaffold dispatches exactly this way, which meant
+  `executeVirtualUserRun` was never registered: every virtual-user run sat at
+  `running` forever with nothing logged, because the scaffold's own
+  `.catch(() => {})` swallowed the rejection.
+
+  The receiver is now unwrapped through non-null assertions and parentheses
+  before it is matched.
+
+- Updated dependencies [88629af]
+- Updated dependencies [f1ccfe3]
+  - @pikku/core@0.12.96
+
 ## 0.12.65
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -29,7 +29,7 @@ import { resolvePermissions } from '../utils/permissions.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { ErrorCode } from '../error-codes.js';
 import { findPiiPaths } from '../utils/check-pii-output.js';
-import { findRevealedSecretSinks } from '../utils/check-secret-sinks.js';
+import { findClassifiedSinks } from '../utils/check-classified-sinks.js';
 import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
@@ -884,16 +884,25 @@ export const addFunctions = (logger, node, checker, state, options) => {
     // it runs ONLY when explicitly requested (`pikku all --security`) — see the
     // classificationCheck option. Default codegen skips it entirely.
     if (options.classificationCheck) {
-        // A revealed vault secret is invisible to the return-type scan below when it
-        // is written out mid-body rather than returned, so walk the sinks too.
-        for (const violation of findRevealedSecretSinks(checker, handler)) {
+        // A revealed vault secret — or a PII column — is invisible to the return-type
+        // scan below when it is written out mid-body rather than returned, so walk
+        // the sinks too.
+        for (const violation of findClassifiedSinks(checker, handler)) {
             logger.diagnostic({
                 severity: 'error',
-                code: ErrorCode.SECRET_REVEALED_INTO_SINK,
-                message: `Function '${name}' passes a revealed secret to '${violation.sink}' ` +
-                    `at line ${violation.line} (path '${violation.path}').\n  ` +
-                    `A vault secret must not be written to a log, an audit, a queue, an email or a webhook. ` +
-                    `Pass the value only to the client that needs it, and reveal it there.`,
+                code: violation.classification === 'secret'
+                    ? ErrorCode.SECRET_REVEALED_INTO_SINK
+                    : ErrorCode.PII_INTO_SINK,
+                message: violation.classification === 'secret'
+                    ? `Function '${name}' passes a revealed secret to '${violation.sink}' ` +
+                        `at line ${violation.line} (path '${violation.path}').\n  ` +
+                        `A vault secret must not be written to a log, an audit, a queue, an email or a webhook. ` +
+                        `Pass the value only to the client that needs it, and reveal it there.`
+                    : `Function '${name}' passes personal data to '${violation.sink}' ` +
+                        `at line ${violation.line} (path '${violation.path}').\n  ` +
+                        `A log, the console and a webhook all leave your control — they are shipped to third parties and retained ` +
+                        `long past the request. Log an id instead, or narrow the value to a non-identifying field. ` +
+                        `An email to the data subject, an audit in your own database and a queue on your own infrastructure are fine.`,
             });
         }
         const sig = checker.getSignatureFromDeclaration(handler);

package/dist/add/add-rpc-invocations.js

@@ -13,6 +13,25 @@ function outerParent(node) {
 function findCastArg(args) {
     return args.find(hasTypeCast);
 }
+/**
+ * The `rpc` in `rpc.invoke(...)`, seen through whatever the author wrote to
+ * satisfy the type checker.
+ *
+ * `rpc` is optional on the wire, so a caller that knows it is there reaches for
+ * `rpc!.invoke(...)` — and a non-null assertion is a node of its own, not the
+ * identifier underneath it. Matching only the bare identifier meant those calls
+ * were never recorded as invocations, which is silent rather than loud: the
+ * target is not `expose: true`, so nothing else puts it in the registry, and
+ * the dispatch fails with "Function not found" at run time on a call site that
+ * type-checked. Parentheses are unwrapped for the same reason.
+ */
+function invocationReceiver(node) {
+    let inner = node;
+    while (ts.isNonNullExpression(inner) || ts.isParenthesizedExpression(inner)) {
+        inner = inner.expression;
+    }
+    return inner;
+}
 /**
  * Helper to extract namespace from a namespaced function reference like 'ext:hello'
  */
@@ -62,10 +81,14 @@ export function addRPCInvocations(node, state, logger) {
             }
         }
         // Check for rpc.invoke('...') calls
+        const invokeReceiver = ts.isPropertyAccessExpression(expression)
+            ? invocationReceiver(expression.expression)
+            : undefined;
         if (ts.isPropertyAccessExpression(expression) &&
             expression.name.text === 'invoke' &&
-            ts.isIdentifier(expression.expression) &&
-            expression.expression.text === 'rpc') {
+            invokeReceiver &&
+            ts.isIdentifier(invokeReceiver) &&
+            invokeReceiver.text === 'rpc') {
             // Skip PKU940 for generated files — they may contain intentional casts
             // (e.g. the paginated useInfiniteQuery hook in pikku-react-query.gen.ts).
             const sourceFileName = node.getSourceFile().fileName;

package/dist/error-codes.d.ts

@@ -79,7 +79,8 @@ export declare enum ErrorCode {
     SECRET_SERVICE_ALIASED = "PKU950",
     SECRET_NOT_DECLARED = "PKU951",
     SECRET_KEY_NOT_STATIC = "PKU952",
-    SECRET_REVEALED_INTO_SINK = "PKU953"
+    SECRET_REVEALED_INTO_SINK = "PKU953",
+    PII_INTO_SINK = "PKU954"
 }
 /**
  * Severity of a tracked, coded diagnostic. `critical` always blocks the build;

package/dist/error-codes.js

@@ -104,4 +104,5 @@ export var ErrorCode;
     ErrorCode["SECRET_NOT_DECLARED"] = "PKU951";
     ErrorCode["SECRET_KEY_NOT_STATIC"] = "PKU952";
     ErrorCode["SECRET_REVEALED_INTO_SINK"] = "PKU953";
+    ErrorCode["PII_INTO_SINK"] = "PKU954";
 })(ErrorCode || (ErrorCode = {}));

package/dist/inspector.js

@@ -371,6 +371,10 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     state.filesAndMethodsErrors = errors;
     logger.debug(`Get files and methods completed in ${(performance.now() - startFilesAndMethods).toFixed(2)}ms`);
     if (!options.setupOnly) {
+        // Everything below re-derives from the state this pass just built, so it
+        // supersedes whatever an earlier pass concluded about a source graph the
+        // run has since finished generating into.
+        logger.beginValidationPass?.();
         const startAggregate = performance.now();
         // Apply the inspected auth handler service set before aggregation so it
         // flows into requiredServices (the generated handler's own func is opaque).
@@ -408,6 +412,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateScopeReferences(logger, state);
         validateSystemRoleScopes(logger, state);
         validatePersonaRoles(logger, state);
+        logger.endValidationPass?.();
     }
     state.program = program;
     return state;

package/dist/types.d.ts

@@ -300,6 +300,24 @@ export interface InspectorLogger {
     /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */
     critical: (code: ErrorCode, message: string) => void;
     hasCriticalErrors: () => boolean;
+    /**
+     * Opens a validation pass, discarding whatever a previous one recorded.
+     *
+     * A single `pikku all` inspects several times, because generating the
+     * scaffold, the leaf indexes and the type files each changes the source graph
+     * the next inspection reads. The validators are pure functions of that graph
+     * and every full inspection re-runs all of them, so the newest pass is always
+     * the complete one and the ones before it are strictly superseded.
+     *
+     * Without this the diagnostics accumulated instead, and a run failed on a
+     * complaint about its own half-built input: a project whose roles reference
+     * scaffold-declared scopes was reported as failing even though the pass that
+     * ran once the scaffold existed was clean. Optional so a host supplying its
+     * own logger keeps working — one that omits it simply never discards.
+     */
+    beginValidationPass?: () => void;
+    /** Closes the pass opened by `beginValidationPass`. */
+    endValidationPass?: () => void;
 }
 export type AddWiring = (logger: InspectorLogger, node: ts.Node, checker: ts.TypeChecker, state: InspectorState, options: InspectorOptions) => void;
 export interface InspectorFilesAndMethods {

package/dist/utils/check-classified-sinks.d.ts

@@ -0,0 +1,40 @@
+import * as ts from 'typescript';
+export type SinkClassification = 'secret' | 'pii';
+export type SinkViolation = {
+    /** How the value reaches the outside world, e.g. `logger.info`. */
+    sink: string;
+    /** Dotted path to the secret inside the argument, or `<argument>` when bare. */
+    path: string;
+    /** Position of the offending argument, for the diagnostic message. */
+    line: number;
+    /** Which brand was found, so the caller can pick the diagnostic. */
+    classification: SinkClassification;
+};
+/**
+ * Finds revealed vault secrets — and, for the sinks that reject them, PII
+ * columns — that flow into a sink.
+ *
+ * `SecretValue` is nominally typed, so the type system alone stops it reaching
+ * any of these. `.reveal()` is the deliberate escape hatch, and it hands back
+ * `Secret<T>` — the erasable classification brand. That brand is what this scan
+ * follows, which means it catches the revealed value both inline
+ * (`logger.info(s.reveal())`) and through a local binding, because the local's
+ * inferred type carries the brand too.
+ *
+ * PII arrives by the same route without a `.reveal()`: `Pii<T>` is the brand the
+ * generated row types carry, so a column read straight out of the database keeps
+ * it through a local binding and into the call.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`, or `const email: string = user.email`) erases it and this scan
+ * goes quiet. That is the documented limit
+ * of a structural marker: it catches the mistake, not someone determined to
+ * silence it.
+ *
+ * Sinks are matched on the receiver's resolved core interface, which means the
+ * scan needs the services parameter to be typed. Real projects get that from
+ * the generated `#pikku` factory; a hand-rolled file that calls the raw core
+ * factory without annotating its services leaves the parameter `any`, and an
+ * `any` receiver matches nothing.
+ */
+export declare function findClassifiedSinks(checker: ts.TypeChecker, handler: ts.Node): SinkViolation[];

package/dist/utils/check-classified-sinks.js

@@ -0,0 +1,170 @@
+import * as ts from 'typescript';
+import { findPiiPaths } from './check-pii-output.js';
+import { doesTypeExtendsCore } from './does-type-extend-core-type.js';
+/**
+ * A method that writes its arguments somewhere a classified value must never
+ * land, keyed by the core interface that owns it. `'*'` means every method on
+ * the type is a sink, which is true of a logger.
+ *
+ * `rejects` differs per sink because the two brands leak differently. A vault
+ * secret is wrong everywhere: no sink has a legitimate reason to receive one.
+ * PII is wrong only where it leaves the operator's control, or lands somewhere
+ * never designed to hold it:
+ *
+ *   - a log is read far more widely than the record it came from, is usually
+ *     shipped to a third-party aggregator, and is retained long past the
+ *     lifetime of any consent — so PII does not belong in one;
+ *   - a webhook posts to somebody else's server, which is the same disclosure
+ *     with a different transport;
+ *   - an email is addressed to the data subject, and their own name in it is
+ *     the point;
+ *   - an audit is a record in the operator's own database, and naming who did
+ *     what is usually the legal requirement rather than a breach of it;
+ *   - a queue payload stays on the operator's own infrastructure and is
+ *     consumed by their own worker.
+ *
+ * `private` is deliberately absent everywhere: it marks a value that is not
+ * public, which is a statement about who may read the row — not a claim that
+ * writing it down is a disclosure.
+ */
+const SINKS = [
+    { coreType: 'Logger', methods: '*', rejects: ['secret', 'pii'] },
+    { coreType: 'WebhookService', methods: ['send'], rejects: ['secret', 'pii'] },
+    { coreType: 'QueueService', methods: ['add'], rejects: ['secret'] },
+    { coreType: 'EmailService', methods: ['send'], rejects: ['secret'] },
+    {
+        coreType: 'AuditService',
+        methods: ['audit', 'write'],
+        rejects: ['secret'],
+    },
+    { coreType: 'AuditLog', methods: ['write'], rejects: ['secret'] },
+];
+/** `console` has no Pikku type, and is read as widely as any logger. */
+const CONSOLE_REJECTS = ['secret', 'pii'];
+/**
+ * Finds revealed vault secrets — and, for the sinks that reject them, PII
+ * columns — that flow into a sink.
+ *
+ * `SecretValue` is nominally typed, so the type system alone stops it reaching
+ * any of these. `.reveal()` is the deliberate escape hatch, and it hands back
+ * `Secret<T>` — the erasable classification brand. That brand is what this scan
+ * follows, which means it catches the revealed value both inline
+ * (`logger.info(s.reveal())`) and through a local binding, because the local's
+ * inferred type carries the brand too.
+ *
+ * PII arrives by the same route without a `.reveal()`: `Pii<T>` is the brand the
+ * generated row types carry, so a column read straight out of the database keeps
+ * it through a local binding and into the call.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`, or `const email: string = user.email`) erases it and this scan
+ * goes quiet. That is the documented limit
+ * of a structural marker: it catches the mistake, not someone determined to
+ * silence it.
+ *
+ * Sinks are matched on the receiver's resolved core interface, which means the
+ * scan needs the services parameter to be typed. Real projects get that from
+ * the generated `#pikku` factory; a hand-rolled file that calls the raw core
+ * factory without annotating its services leaves the parameter `any`, and an
+ * `any` receiver matches nothing.
+ */
+export function findClassifiedSinks(checker, handler) {
+    const violations = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
+            const sink = describeSink(checker, node.expression);
+            if (sink) {
+                for (const arg of node.arguments) {
+                    const found = findClassifiedExpression(checker, arg, sink.rejects);
+                    if (found) {
+                        violations.push({
+                            sink: sink.name,
+                            path: found.node.getText(),
+                            line: found.node
+                                .getSourceFile()
+                                .getLineAndCharacterOfPosition(found.node.getStart()).line +
+                                1,
+                            classification: found.classification,
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(handler);
+    return violations;
+}
+/**
+ * Finds the first expression inside a sink argument whose own type carries one
+ * of the brands this sink rejects, and returns it so the diagnostic can quote
+ * it.
+ *
+ * This walks the argument rather than typing it whole, because an object
+ * literal in an argument position is contextually typed by the parameter — for
+ * a guarded sink that parameter is `Safe<M>`, and resolving the literal against
+ * it drops the optional brand before it can be read. Each inner expression
+ * (`token.reveal()`, or a reference to a local holding it) carries its own type
+ * regardless of the surrounding context, so reading those is what actually
+ * sees the secret.
+ */
+function findClassifiedExpression(checker, node, rejects, 
+/**
+ * The node is only being read to reach a property of it, so its own type says
+ * nothing about what the call receives. Without this, `user.userId` reports
+ * the row's `email` column: the walk types the `user` receiver on its way
+ * down, and a row type is branded wherever any of its columns are.
+ */
+isReceiver = false) {
+    // Descend first, so an object literal wrapping the secret reports the
+    // expression that actually holds it (`token.reveal()`) rather than the whole
+    // literal. Nothing inside a `SecretValue` receiver is itself branded, so a
+    // bare `token.reveal()` still falls through to the self-check below.
+    for (const child of node.getChildren()) {
+        // A property name is not a value, and typing it re-resolves the property.
+        if (ts.isPropertyAssignment(node) && child === node.name)
+            continue;
+        const childIsReceiver = (ts.isPropertyAccessExpression(node) ||
+            ts.isElementAccessExpression(node)) &&
+            child === node.expression;
+        const found = findClassifiedExpression(checker, child, rejects, childIsReceiver);
+        if (found)
+            return found;
+    }
+    if (!isReceiver && ts.isExpression(node) && !ts.isStringLiteralLike(node)) {
+        const type = checker.getTypeAtLocation(node);
+        /* `secret` outranks `pii` when a value somehow carries both, so the caller
+           reports the more serious of the two rather than whichever came first. */
+        for (const classification of ['secret', 'pii']) {
+            if (!rejects.includes(classification))
+                continue;
+            const hit = findPiiPaths(checker, type).some((f) => f.classification === classification);
+            if (hit)
+                return { node, classification };
+        }
+    }
+    return undefined;
+}
+/**
+ * Names the sink a call writes to, or undefined when the call is not one.
+ * `console` is matched by identifier because it is a global with no Pikku type;
+ * everything else is matched on its resolved core interface so a renamed
+ * service or a decorator still counts.
+ */
+function describeSink(checker, callee) {
+    const method = callee.name.text;
+    const receiver = callee.expression;
+    if (ts.isIdentifier(receiver) && receiver.text === 'console') {
+        return { name: `console.${method}`, rejects: CONSOLE_REJECTS };
+    }
+    const receiverType = checker.getTypeAtLocation(receiver);
+    for (const { coreType, methods, rejects } of SINKS) {
+        if (methods !== '*' && !methods.includes(method))
+            continue;
+        if (doesTypeExtendsCore(receiverType, checker, new Set(), coreType)) {
+            return { name: `${receiver.getText()}.${method}`, rejects };
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.65",
+  "version": "0.12.67",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.95"
+    "@pikku/core": "^0.12.97"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.95",
+    "@pikku/core": "^0.12.97",
     "@types/node": "^24.13.3"
   },
   "engines": {

package/src/add/add-functions.ts

@@ -43,7 +43,7 @@ import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import { findPiiPaths } from '../utils/check-pii-output.js'
-import { findRevealedSecretSinks } from '../utils/check-secret-sinks.js'
+import { findClassifiedSinks } from '../utils/check-classified-sinks.js'
 import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js'
 import type { NodeType } from '@pikku/core/node'
 
@@ -1230,17 +1230,27 @@ export const addFunctions: AddWiring = (
   // it runs ONLY when explicitly requested (`pikku all --security`) — see the
   // classificationCheck option. Default codegen skips it entirely.
   if (options.classificationCheck) {
-    // A revealed vault secret is invisible to the return-type scan below when it
-    // is written out mid-body rather than returned, so walk the sinks too.
-    for (const violation of findRevealedSecretSinks(checker, handler)) {
+    // A revealed vault secret — or a PII column — is invisible to the return-type
+    // scan below when it is written out mid-body rather than returned, so walk
+    // the sinks too.
+    for (const violation of findClassifiedSinks(checker, handler)) {
       logger.diagnostic({
         severity: 'error',
-        code: ErrorCode.SECRET_REVEALED_INTO_SINK,
+        code:
+          violation.classification === 'secret'
+            ? ErrorCode.SECRET_REVEALED_INTO_SINK
+            : ErrorCode.PII_INTO_SINK,
         message:
-          `Function '${name}' passes a revealed secret to '${violation.sink}' ` +
-          `at line ${violation.line} (path '${violation.path}').\n  ` +
-          `A vault secret must not be written to a log, an audit, a queue, an email or a webhook. ` +
-          `Pass the value only to the client that needs it, and reveal it there.`,
+          violation.classification === 'secret'
+            ? `Function '${name}' passes a revealed secret to '${violation.sink}' ` +
+              `at line ${violation.line} (path '${violation.path}').\n  ` +
+              `A vault secret must not be written to a log, an audit, a queue, an email or a webhook. ` +
+              `Pass the value only to the client that needs it, and reveal it there.`
+            : `Function '${name}' passes personal data to '${violation.sink}' ` +
+              `at line ${violation.line} (path '${violation.path}').\n  ` +
+              `A log, the console and a webhook all leave your control — they are shipped to third parties and retained ` +
+              `long past the request. Log an id instead, or narrow the value to a non-identifying field. ` +
+              `An email to the data subject, an audit in your own database and a queue on your own infrastructure are fine.`,
       })
     }
 

package/src/add/add-rpc-invocations.test.ts

@@ -110,4 +110,54 @@ export const routes = { stream: { func: ref('console:streamWorkflowRun') } }
       await rm(dir, { recursive: true, force: true })
     }
   })
+
+  test('a non-null assertion on the receiver is still an invocation', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
+export async function doWork() {
+  return rpc!.invoke('executeVirtualUserRun')
+}
+`,
+    })
+    try {
+      assert.ok(state.rpc.invokedFunctions.has('executeVirtualUserRun'))
+      const invoked = [...state.rpc.invokedFunctionsByFile.values()][0]!
+      assert.deepStrictEqual([...invoked], ['executeVirtualUserRun'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('a parenthesised receiver is still an invocation', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
+export async function doWork() {
+  return (rpc!).invoke('listTasks')
+}
+`,
+    })
+    try {
+      assert.ok(state.rpc.invokedFunctions.has('listTasks'))
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('invoke on some other receiver is left alone', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const client: { invoke: (name: string, data?: unknown) => Promise<unknown> } | undefined
+export async function doWork() {
+  return client!.invoke('notAnRpc')
+}
+`,
+    })
+    try {
+      assert.ok(!state.rpc.invokedFunctions.has('notAnRpc'))
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
 })

package/src/add/add-rpc-invocations.ts

@@ -20,6 +20,26 @@ function findCastArg(
   return args.find(hasTypeCast)
 }
 
+/**
+ * The `rpc` in `rpc.invoke(...)`, seen through whatever the author wrote to
+ * satisfy the type checker.
+ *
+ * `rpc` is optional on the wire, so a caller that knows it is there reaches for
+ * `rpc!.invoke(...)` — and a non-null assertion is a node of its own, not the
+ * identifier underneath it. Matching only the bare identifier meant those calls
+ * were never recorded as invocations, which is silent rather than loud: the
+ * target is not `expose: true`, so nothing else puts it in the registry, and
+ * the dispatch fails with "Function not found" at run time on a call site that
+ * type-checked. Parentheses are unwrapped for the same reason.
+ */
+function invocationReceiver(node: ts.Expression): ts.Expression {
+  let inner = node
+  while (ts.isNonNullExpression(inner) || ts.isParenthesizedExpression(inner)) {
+    inner = inner.expression
+  }
+  return inner
+}
+
 /**
  * Helper to extract namespace from a namespaced function reference like 'ext:hello'
  */
@@ -80,11 +100,15 @@ export function addRPCInvocations(
     }
 
     // Check for rpc.invoke('...') calls
+    const invokeReceiver = ts.isPropertyAccessExpression(expression)
+      ? invocationReceiver(expression.expression)
+      : undefined
     if (
       ts.isPropertyAccessExpression(expression) &&
       expression.name.text === 'invoke' &&
-      ts.isIdentifier(expression.expression) &&
-      expression.expression.text === 'rpc'
+      invokeReceiver &&
+      ts.isIdentifier(invokeReceiver) &&
+      invokeReceiver.text === 'rpc'
     ) {
       // Skip PKU940 for generated files — they may contain intentional casts
       // (e.g. the paginated useInfiniteQuery hook in pikku-react-query.gen.ts).