Skip to content

Effect Plugin Interface ​

Definition of the plugin interface for classifying call_expressions as side effects (effects). One effect plugin is responsible for one library/framework domain (e.g. Prisma / NestJS / Stripe / Redis).

References:


1. Purpose ​

From the textual form of a call_expression (prisma.invoice.create) and its surrounding context, determine what effect the call represents (db.write / x-stripe:charge, etc.).

The language plugin only provides "what was called" at the string level. The effect plugin determines "what it means" in a language-independent way.

2. Plugin Responsibilities ​

2.1 In scope ​

  • Declare effect ids (individual / prefix) in the manifest
  • Receive a CallCandidate and determine whether it is an effect this plugin recognizes
  • If recognized, return an EffectClassification (effectId / confidence / derivedBy)
  • If recognized but not classifiable from the call site, return an EffectDecline naming the reason (§4.5)
  • If not recognized, return null
  • Optionally, add calls this plugin recognizes to drop-list category C (logger-oriented effect plugins only)

2.2 Out of scope ​

  • Parsing sources (the language plugin's job)
  • Walking the AST
  • Creating or modifying Symbols themselves
  • Overriding results classified by other plugins
  • Writing directly to Symbol.derivedBy[] (only returns a per-effect derivedBy)
  • Applying config.suppress / keep (the core)

The responsibility is confined to a pure function "callee → effect classification". As a result:

  • Effect plugins reduce to almost purely declarative pattern matching
  • Unit testing is easy (feed a callee string and assert the expected effectId)
  • They are reusable across languages (the same Prisma plugin is expected to work for TS and Python alike)

3. Lifecycle ​

1. The registry validates the manifest and loads the plugin
2. plugin.init() is called with ctx (registry/config)
3. Each time a language plugin extracts CallCandidate[] in walkBody:
     for each call, the enabled effect plugins are invoked in config order
       plugin.classify(call, ctx) → EffectClassification | EffectDecline | null
     the first classification is adopted; a call none classifies keeps its declines (§5)
4. After all files, plugin.cleanup?() is called

4. Interface ​

The actual types are defined in the types package of @aburi/core. This document shows the signatures of the contract surface.

4.1 EffectPlugin ​

ts
interface EffectPlugin {
  manifest: PluginManifest                   // type: "effects"
  init(ctx: PluginContext): Promise<void>
  cleanup?(): Promise<void>

  // effect classification (ideally implemented as a pure function)
  classify(call: CallCandidate, ctx: ClassifyContext): EffectClassification | EffectDecline | null

  // optional: additions to drop-list category C (implemented by logger-oriented plugins only)
  dropCallees?: string[]                     // identifier path prefixes (e.g. "pino", "winston")
}

4.2 CallCandidate (from the language plugin) ​

Normatively defined in lang-plugin.md §4.4. This document only references the same type. Summary: the 6 fields { target, line, argumentCount, inAwait, inNew, literalArgs }, and three optional ones, dynamicReceiver, receiverType and thisBinding. literalArgs covers cases such as wanting to inspect the contents of an SQL string (non-literals are null). receiverType is the named type the receiver is declared with, when the language plugin can read one (§5.4).

target is contract-guaranteed non-empty with no empty segments, and an ImportEdge's source, symbols entries and namespaceBinding are non-empty too (lang-plugin.md §4.4, "Normalized-callee contract"). Effect plugins enforce that contract instead of coding around it, through the guards in @aburi/plugin-registry/plugin-input. Each throws a PluginInputError under its own code:

  • assertNonEmptySegments splits target into its segments, and raises unnormalized-callee when the target or a segment is empty.
  • assertImportEdgeSource raises unnormalized-import-source for an empty ImportEdge.source. hasMatchingImport runs it over every edge before matching a module specifier.
  • assertImportBinding raises unnormalized-import-binding for an ImportEdge.symbols entry with an empty half.
  • assertNamespaceBinding raises unnormalized-namespace-binding for an empty ImportEdge.namespaceBinding.

The error names the plugin and the file, so a consumer branches on code, as it does on the core's and the registry's errors, without reading the message. The guards live in the registry rather than in each plugin so the next effect plugin inherits identical codes, identical messages and identical fail-fast ordering. They ship as a dedicated subpath so importing them does not pull the registry's manifest validator (and its schema compilation) into a classifier's startup path.

A violation raised by these guards is not a classification outcome, so it is exempt from the EP3 degradation in §10: a classifier that throws while deciding is a plugin bug the run can absorb by treating the call as unclassified, whereas an unnormalized callee means every downstream classification of that file was computed from a value the pipeline promised could not exist. Degrading it to null would turn an upstream parser bug into a quietly under-populated IR — the one outcome the guards exist to prevent. See EP3a.

What the throw costs is the file, not the run: the core's per-file boundary (lang-plugin.md §7.2) withdraws it, names it in ScanResult.skipped and in ScanResult.extractionFailures under the guard's code, logs a warning, and makes aburi scan exit non-zero. That is not the degradation this section rules out — a degraded call is silent and a withdrawn file is counted, named, and quoted back with what the guard said.

4.3 ClassifyContext ​

ts
interface ClassifyContext {
  owner: OwnerSummary                        // summary of the Symbol containing the call
  file: FileSummary                          // file information (including imports)
  language: string                           // "ts" / "py" / "rs" etc.
  registry: VocabRegistry
  config: AburiConfig
}

interface OwnerSummary {
  id: string                                 // id of the owning Symbol
  kind: SymbolKind
  name: string
  extKind: string | null                     // value already determined by the framework plugin
  decorators: OwnerDecorator[]
  component: string | null
}

type OwnerDecorator = Pick<Decorator, 'name' | 'qualifier' | 'boundary'>

interface FileSummary {
  path: string
  imports: ImportEdge[]                      // all imports extracted by the language plugin
}

Providing imports lets the effect plugin distinguish whether "the identifier prisma comes from @prisma/client or is a local homegrown variable".

decorators[].qualifier is Decorator.qualifier (ir-schema.md) passed through: the receiver that @tsed.Post() was written through (tsed), absent for a bare @Post(). Resolving it against imports answers the same question for a decorator, by the rule lang-plugin.md §5.2.2 gives: only the first dot-separated segment can name a local binding, so @a.b.C() resolves through a, and comparing the whole a.b with ImportEdge.namespaceBinding finds nothing. The other Decorator fields (raw, arguments, line) are not passed; a field added to Decorator reaches effect plugins only once OwnerDecorator names it, and a type test in @aburi/types fails pnpm typecheck until that is decided (pnpm test alone cannot fail it, because expectTypeOf erases at runtime).

4.4 EffectClassification ​

ts
interface EffectClassification {
  effectId: string                           // a core id from ir-schema §9.1 or x-<plugin>:<action>
  confidence: 'high' | 'medium' | 'low'      // ir-schema §5.4
  derivedBy: string                          // e.g. "effects-plugin:prisma:create"
}

The returned effectId must fall under the manifest's provides.effects[].id or provides.effectPrefixes[]. The registry detects violations at extraction time and raises an error.

4.5 EffectDecline ​

ts
interface EffectDecline {
  declined: string                           // e.g. "effects-plugin:trpc:server-file-query"
}

null says "not mine". A decline says "mine, and I will not say which effect": the call has the library's shape, but the plugin cannot classify it soundly. The official plugins decline three shapes:

PluginCalldeclinedWhy it cannot classify
effects-trpca procedure call ending in .query(), in a file that imports @trpc/server as well as a tRPC clienteffects-plugin:trpc:server-file-querythe router's builder (publicProcedure.input(schema).query(resolver)) is spelled like a client call (client.user.byId.query()), and nothing in the callee tells them apart
effects-prisma$queryRaw, $queryRawUnsafe, $queryRawTyped, $executeRaw, $executeRawUnsafe or $runCommandRaw called on a receiver, in a file that imports Prismaeffects-plugin:prisma:raw-querya raw query — SQL, or a MongoDB command for $runCommandRaw — can read or write, and the query is not in the callee
effects-drizzle.execute(statement) with an argument, on a receiver whose name mentions a Drizzle client word (db, tx, database, conn, …), matched word-wise as for the confidence tier (§5.4), in a file that imports Drizzleeffects-plugin:drizzle:raw-sqlraw SQL can read or write, and the statement is not in the callee

The tRPC decline is keyed on the file, not on the call. In a file that imports both sides, every .query of three or more segments is declined: the router's own builders (t.procedure.query(resolver)) and a .query that is not tRPC's at all (db.pool.query(sql)) included, so aburi explain lists them under the Symbol that makes them. The reason states the file's situation — a query in a file that also serves tRPC — not that the call is a tRPC call. Narrowing it to calls on a client would take the binding a createTRPCClient(...) result is assigned to, which ClassifyContext does not carry.

The core records the decline in stats.declinedCalls[] (ir-schema.md §2): the plugin, the owner Symbol, the call's target and line, and declined as the entry's reason. Without it, a call the plugin chose to leave unclassified and a call no plugin recognized look the same in the IR. aburi explain lists a Symbol's entries under ## Declined effects (markdown-projection.md §7).

declined is the plugin's reason, in the plugin's words. Spell it as derivedBy is spelled, effects-plugin:<plugin>:<reason>, so that a reader can tell which plugin wrote it and two runs over the same code write the same string. It must be a string that is not empty and not only whitespace; any other value fails the run with scan-plugin-misconfigured, naming the plugin, when the plugin returns it and whatever a later plugin answers for the call (EP14b). The Document holds it in Unicode NFC, like every string it contains (ir-schema.md §1.2), and quotes it: invariant #19 does not check its spelling.

An answer is a classification or a decline, never both. TypeScript accepts an object carrying effectId and declined as either member of the union, so the core refuses it at run time: an answer with both keys fails the run with scan-plugin-misconfigured, whatever their values (EP14c). Reading it as one of the two would drop the other in silence.

5. Classification Algorithm ​

5.1 first-match-wins ​

for each call in symbol.calls:
  declines = []
  for each effect_plugin in config-order:
    result = effect_plugin.classify(call, ctx)
    if result carries both effectId and declined:
      fail the run    # scan-plugin-misconfigured (EP14c)
    if result is an EffectClassification:
      assign call to effects[] with result
      break    # subsequent plugins are not invoked
    if result is an EffectDecline:
      declines += (effect_plugin, result.declined)    # not a match: the next plugin is still asked
  else:
    leave call in calls[]
    record declines in stats.declinedCalls[]

Plugins earlier in config order take priority. Placing a project-specific plugin above the standard plugins lets it take precedence.

A decline does not end the dispatch. A plugin lower in the order that does classify the call wins it, and the declines are discarded: the call reached effects[], so no effect is missing (EP14a). Only a call that stays in calls[] keeps its declines, one entry for each plugin that declined it.

5.1.1 Budget for classify() ​

The core times each plugin's classify(call, ctx) invocation against a per-call budget. Default 50ms.

  • Override: config.classifyTimeoutMs (default 50, min 10, max 5000)
    • For plugins containing an SQL parser, raising it to 200-500ms is realistic
    • No per-plugin override (a single config value shared by all plugins)
  • Budget exceeded → the classification is kept, exactly as if the call had been fast: a classification moves the call to effects[] (EP6); a null or a decline passes the call to the next plugin in config order (EP4) and leaves it in calls[] when no plugin claims it (EP5, EP14). A kept answer meets the vocabulary check like any other (EP1), so an undeclared id ends a strict run whether or not its call was slow. classify() is synchronous, so the clock is read after it returns: the work is already done, and discarding the answer would save nothing while making the IR depend on how busy the machine was. A cold first call (module initialisation, JIT, a GC pause) is the usual overrun
  • Overrun recording: each overrun (plugin, Symbol, budget) is recorded in stats.effectClassifyTimeouts[], and the CLI's scan prints their count as one warning (N effect classification(s) ran past the per-call budget; their results were kept.)
    • An overrun changes this record and nothing else in the Document: effects[], calls[] and every fingerprint are what they would have been had the call been fast. The parse budget is different in kind: a file over parseTimeoutMs is left out of the Document altogether (lang-plugin.md §7.1.2)
    • CI can compare effectClassifyTimeouts across runs to spot plugin performance regressions
  • Plugin implementations must be synchronous: a classify() that returns a Promise fails the run (scan-plugin-misconfigured)
  • A decline costs one small record per declining plugin, kept only if the call stays in calls[]; its reason is checked when it is returned, whatever a later plugin answers (EP14b). A plugin can decline every call in a large workspace without a log line per call

The budget does not stop a slow plugin — nothing can interrupt a synchronous call — it names one. A plugin that overruns on every call shows up in the stats, call by call, and the remedy is the plugin's.

An overrun is recorded while an input-contract violation (§4.2) fails the run, and the split is deliberate: a slow classifier still received a well-formed callee and returned a well-formed answer, so the run is sound and stats.effectClassifyTimeouts[] records which call was slow. A violated input contract has no such bound: the value was never one the pipeline could produce, so nothing downstream of it is trustworthy. Record what you can account for; fail on what you cannot.

5.2 Why multiple classification is disallowed ​

There is a temptation to record prisma.invoice.create as both db.write (core) and x-prisma:invoice.create (Prisma detail), but currently:

  • The IR's Symbol.effects[] grows complex (differing ids side by side for the same target/line)
  • The diff report's ordering conventions break down (which one is canonical?)
  • The comprehension load on consumers rises

A single effectId is adopted via first-match-wins. Multiple classification remains an option for a future release via a separate field (Effect.aliases?: string[]) — see the roadmap.

5.3 Expressing "do not classify" in a higher-priority plugin ​

Priority control such as "the Prisma plugin should return x-prisma:create instead of db.write, so place it above the generic plugin that returns core db.*" is done via config order.

Conversely, when a higher-priority plugin wants to defer specific calls to lower ones, it returns null and the call flows down. A decline flows down in the same way. The difference is what remains when no plugin below claims the call: after a null nothing remains, and after a decline the plugin's reason remains in stats.declinedCalls[] (§4.5).

5.4 Receiver identification and confidence ​

A method name is not a library. delete, create, update and select are shared vocabulary across Map, Set, the DOM, RxJS stores and every HTTP router, so a classifier that recognizes a call by its terminal alone will attribute other libraries' calls to its own.

The file-level import gate does not settle this. It answers "does this file use the library", which a file is free to answer yes to while most of its calls belong to something else — an Express router beside its Drizzle queries, a Map cache beside a Prisma client. A gate that a mixed file passes wholesale cannot be the last word for the individual calls inside it.

A plugin that matches on shared vocabulary therefore weighs three more things before it commits:

  1. Argument shape. The library's own signatures rule out collisions for free: no Prisma delegate method and no Drizzle query-builder root takes a bare literal, which is exactly what router.delete("/users/:id", handler) opens with. A first argument the library's API could never take is null, not a low-confidence effect; hasLiteralFirstArgument from @aburi/plugin-registry/plugin-input is the shared reader for that literal. A missing argument can be the same signal, but only where a plugin names it per method: Drizzle's insert, update and delete require a table and its transaction and batch a callback or a statement array, and a zero-argument call to any of them is null whatever the receiver. That floor is not the overflow of item 3 turned around. A zero-argument batch() / transaction() / update() / delete() has named owners other than the library (Firestore's batch(), an unmanaged Sequelize or Knex transaction(), an Active Record model's user.delete(), a class's own method), where an overflow has none; and a miscount can only reach zero from a comment-only argument list (db.transaction(/* cb */)), source that does not run, where a miscount above the maximum is open-ended. It does not claim the source is valid: broken source and another library's call are not separable from the callee string, and recording a phantom db.write or db.transaction is the costlier mistake, as withdrawing the file over a zero-argument transaction() or batch() was. There is no shared reader for it; a plugin reads the floor from its own method table, beside the maximum of item 3, and checks argumentCount against it.

  2. Receiver name. The segment holding the client (prisma in this.prisma.user.create, db in db.select) is matched word-wise against the plugin's own vocabulary of client binding names — identifierWords / identifierMentions in the same module, so prismaClient and readReplicaDb match while feedback does not match db. Keep the vocabulary to words that actually separate a client from everything else sharing the verbs: client matches apiClient and httpClient, whose <client>.<resource>.<verb> shape is a Prisma delegate's exactly, so an entry like that hands the collision the top tier instead of catching it.

  3. Argument count. Read the arity off the library's own vocabulary table rather than flattening it to a constant — Postgres' selectDistinctOn(columns, projection) and transaction(callback, config) take two — and treat an overflow as evidence, not proof. CallCandidate.argumentCount is a syntactic count, and a classifier reading it as a signature is reading it for more than it promises; a miscount that drops the call erases a real effect and logs nothing, which is the one failure mode with no trace.

The last two set the tier, they do not gate the classification:

signaloutcome
receiver names a client binding, arity fitsconfidence: "high"
receiver is a name the plugin cannot placeconfidence: "medium"
dynamicReceiver (a collapsed expression)confidence: "medium", whatever it is spelled
more arguments than the method takesconfidence: "medium"

medium rather than null because the two cases behind an unrecognized name — a client under a house naming convention, and an unrelated object of the same shape — are not separable from the callee string, and effect plugins never see the AST (§6.1): the binding that would separate them reaches a plugin only where CallCandidate.receiverType carries it. Dropping the first is as wrong as claiming the second at the tier a hand-annotated effect gets, so the uncertainty is recorded instead of resolved by guessing. This is the same tier @aburi/framework-express assigns a route that matches the shape without an import anchor.

A plugin whose vocabulary is its own — a @Controller decorator resolved back to the framework's package — has nothing to disambiguate and stays at high on shape alone. A $-prefixed name the library owns outright is close to that, but not the same thing: the receiver still decides whose $transaction it is.

Receiver type. Where the language plugin reads the type a receiver is declared with (CallCandidate.receiverType, lang-plugin.md §4.4), a match identifies the receiver as a recognised name does: this.events.emit(…) beside constructor(private events: EventEmitter2) is EventEmitter2's emit whatever the field is called. A plugin that compares it does so against what the file's imports bind — the class's own name, the local an aliased import gives it, <namespace>.<class>, or the local of a default import where the module exports the class as its default — never against a spelling it expects, so a homegrown class of the same name, or one from another module, is not taken for the library's. A match is high on its own. The name check still comes first, so a type that binds something else does not veto a recognised name, and a receiver both checks place keeps the name's tag; the field's absence is no evidence either way.

6. Cooperation with Language Plugins ​

6.1 Information reaching the effect plugin ​

Once the language plugin's walkBody returns a CallCandidate, the core routes it to each effect plugin. Effect plugins never access the AST.

6.2 Invocation relative to owner Symbol determination ​

Some effect plugins make decisions that depend on the owner's extKind (already determined by the framework plugin) — e.g. NestJS lifecycle is only meaningful inside framework:nestjs:provider.

Therefore the extraction order is (see lang-plugin.md §5.3):

extractSymbols → framework.classifySymbol → walkBody → effects.classify

By the time an effect plugin is invoked, owner.extKind has been determined.

6.3 The same call never has multiple owners ​

A call_expression belongs to a single owning Symbol (nested anonymous functions are absorbed into the parent, ir-schema.md §3.3). Effect plugins never face ambiguity in identifying the owner.

7. Drop Additions by Logger-Oriented Plugins ​

Providing dropCallees: string[] on the plugin object (§4.1; the manifest has no such field) adds the given callee prefixes to the core's drop-list category C (drop-list.md §5.2).

Example: if the effects-pino plugin declares ["pino", "child"], then pino.info(...) / child.info(...) are excluded from effects/calls.

Writing a drop-only plugin is also possible (provides.effects: [] but declaring dropCallees only).

8. Official Effect Plugins (planned) ​

pluginexample recognized calleesmain effect ids
@aburi/effects-nestEventEmitter2 / eventBus .emit(...), and .emit(...) on a field declared as EventEmitter2event.publish
@aburi/effects-prismaprisma.*.{find*,create,update,upsert,delete}db.read / db.write
@aburi/effects-drizzledb.select().from(...) / db.insert(...)db.read / db.write
@aburi/effects-trpctrpc.*.{query,mutation} and the React Query hooksnetwork.rpc
@aburi/effects-axiosaxios.{get,post,put,patch,delete}network.http
@aburi/effects-fetchfetch(...) (global)network.http
@aburi/effects-bullmqqueue.add(...) / workerqueue.publish / queue.consume
@aburi/effects-redisclient.{get,set,del}x-redis:read / x-redis:write (core state.* is in-process only, so Redis is expressed via plugin extension)
@aburi/effects-pinopino.* / child.*dropCallees only (logger exclusion)
@aburi/effects-winstonwinston.*same as above
@aburi/effects-oteltracer.* / metrics.* / span.*same as above

Implementation details of each plugin live in their respective READMEs. Today effects-nest, effects-prisma, effects-drizzle and effects-trpc are implemented; the rest are planned — see the roadmap.

9. Pattern-Matching Implementation Examples ​

9.1 Prisma effect plugin (pseudocode) ​

ts
import {
  assertNonEmptySegments,
  hasLiteralFirstArgument,
  hasMatchingImport,
  identifierMentions,
} from '@aburi/plugin-registry/plugin-input'

const READ_METHODS = /^(findUnique|findFirst|findMany|count|aggregate|groupBy)$/
const WRITE_METHODS = /^(create|createMany|update|updateMany|upsert|delete|deleteMany)$/
const TX_METHOD = '$transaction'
const RAW_QUERY_METHODS =
  /^\$(queryRaw|queryRawUnsafe|queryRawTyped|executeRaw|executeRawUnsafe|runCommandRaw)$/

// Words a Prisma client binding is spelled with. `client` is deliberately absent: it
// matches `apiClient` / `httpClient`, whose `<client>.<resource>.<verb>` shape is a
// delegate call's shape exactly (§5.4).
const PRISMA_CLIENT_WORDS = new Set(['prisma', 'db', 'database', 'orm', 'tx', 'trx'])

export const plugin: EffectPlugin = {
  manifest: { /* see plugin-effects-prisma.json */ },

  async init(ctx) {},

  classify(call, ctx) {
    const origin = { plugin: 'effects-prisma', filePath: ctx.file.path }

    // decompose the identifier chain: "prisma.invoice.create" → ["prisma", "invoice", "create"]
    // The shared guard rejects an unnormalized callee instead of splitting it silently, and
    // runs before the import gate so an upstream bug is not narrowed to Prisma files.
    const { segments: parts, last: method } = assertNonEmptySegments(call.target, origin)

    // Does this file use Prisma at all? Necessary, never sufficient (§5.4).
    if (!hasMatchingImport(ctx.file.imports, origin, (source) => source === '@prisma/client')) {
      return null
    }

    // `<client>.$transaction(...)` is 2 segments, and its callback form takes a second
    // options argument — so it is dispatched before the 3-segment delegate shape and
    // carries its own arity.
    if (method === TX_METHOD) {
      if (parts.length < 2) return null
      if (hasLiteralFirstArgument(call)) return null
      return {
        effectId: 'db.transaction',
        confidence: tier(parts[parts.length - 2], call, 2),
        derivedBy: 'effects-plugin:prisma:tx',
      }
    }

    // Whether a raw query reads or writes is in the query, which the call site does not
    // spell: the call is Prisma's, and the plugin declines to name its effect (§4.5).
    // Ahead of the literal check, since `$executeRawUnsafe("…")` takes its SQL as one.
    if (RAW_QUERY_METHODS.test(method) && parts.length >= 2) {
      return { declined: 'effects-plugin:prisma:raw-query' }
    }

    // A delegate call is `<client>.<model>.<verb>`; the client segment is what stops a
    // two-segment `router.create(...)` from matching.
    if (parts.length < 3) return null

    // No delegate takes a bare literal, so `map.delete("id")` is another API.
    if (hasLiteralFirstArgument(call)) return null

    const confidence = tier(parts[parts.length - 3], call, 1)

    if (READ_METHODS.test(method)) {
      return { effectId: 'db.read', confidence, derivedBy: 'effects-plugin:prisma:read' }
    }
    if (WRITE_METHODS.test(method)) {
      return { effectId: 'db.write', confidence, derivedBy: 'effects-plugin:prisma:write' }
    }
    return null
  }
}

// The receiver and the argument count set the tier; neither gates the classification (§5.4).
function tier(receiver, call, maxArguments) {
  if (call.dynamicReceiver) return 'medium'
  if (call.argumentCount > maxArguments) return 'medium'
  // Word-wise against the client vocabulary, so `prismaClient` / `readReplicaDb` match and
  // `cache` / `router` do not — see `namesPrismaClient` in @aburi/effects-prisma.
  return identifierMentions(receiver ?? '', PRISMA_CLIENT_WORDS) ? 'high' : 'medium'
}

9.2 NestJS lifecycle effect plugin (pseudocode) ​

ts
const LIFECYCLE_METHODS = {
  onModuleInit: 'x-nest:lifecycle.on-module-init',
  onApplicationBootstrap: 'x-nest:lifecycle.on-application-bootstrap',
  onModuleDestroy: 'x-nest:lifecycle.on-module-destroy',
  onApplicationShutdown: 'x-nest:lifecycle.on-application-shutdown',
}

export const plugin: EffectPlugin = {
  manifest: { /* see plugin-effects-nest.json */ },
  classify(call, ctx) {
    // If we design effect propagation for "calls to other symbols inside a lifecycle hook body", that is a separate consideration
    // currently "the invocation of the lifecycle hook itself" is not treated as an effect (the framework plugin handles that via extKind)
    return null
  },
  dropCallees: []  // NestJS passes loggers via DI rather than a separate module, so nothing is dropped here
}

(NestJS lifecycle does not appear as calls; it is determined by method name and framework boundary, so it is the framework plugin's responsibility, not the effect plugin's.)

9.3 Stripe effect plugin (pseudocode) ​

ts
import { assertNonEmptySegments, hasMatchingImport } from '@aburi/plugin-registry/plugin-input'

const ACTIONS = {
  charges: 'x-stripe:charge',
  customers: 'x-stripe:customer.create',  // when method is create
  webhooks: 'x-stripe:webhook.deliver',
}

export const plugin: EffectPlugin = {
  manifest: { /* see plugin-effects-stripe.json */ },
  classify(call, ctx) {
    const origin = { plugin: 'effects-stripe', filePath: ctx.file.path }
    const { segments: parts, last: method } = assertNonEmptySegments(call.target, origin)
    if (parts.length < 3) return null
    const resource = parts[parts.length - 2]

    if (!hasMatchingImport(ctx.file.imports, origin, source => source === 'stripe')) return null

    if (resource === 'charges' && method === 'create') {
      return { effectId: 'x-stripe:charge', confidence: 'high', derivedBy: 'effects-plugin:stripe:charge' }
    }
    // ... and so on
    return null
  }
}

10. Verifiable Properties (Test Criteria) ​

IDInputExpected
EP1returning an effectId not in the manifestextraction-time error (detected by the registry)
EP2classify returns the same output for the same inputpurity (no side effects, no held state)
EP3classify throws from its own classification logicnot implemented. Nothing between the classifier and the core's per-file boundary catches a throw, so this behaves as EP3a and withdraws the file. The two are told apart by code: an EP3a violation's extractionFailures entry carries a PluginInputError code (§4.2), and a classifier's own throw carries none of them
EP3aclassify throws an input-contract violation (§4.2)propagates out of classification rather than degrading to an unclassified call; the core's per-file boundary (lang-plugin.md §7.2) then withdraws the file, names it in skipped and in extractionFailures with the guard's code (unnormalized-callee for an empty target segment), and aburi scan exits non-zero
EP42 plugins classify the same callthe first in config order wins (first-match-wins)
EP5classify returns nullthe call stays in Symbol.calls[]
EP6classify returns an EffectClassificationthe call moves to Symbol.effects[] and does not stay in Symbol.calls[]
EP7plugin declaring dropCalleesmatching callees are excluded from effects/calls, same as drop-list §5.2
EP8logger-only plugin with effects: [] and dropCallees: ["pino"]classify keeps returning null, but pino.* is dropped
EP9returning any id under effectPrefixes: ["x-stripe"]OK (no individual declaration needed)
EP10classify returns confidence: 'low'Symbol.effects[].confidence = "low" goes into the IR as-is
EP11a call matching a plugin's shared-vocabulary shape on a receiver the plugin cannot identify (§5.4)the effect is still recorded, at confidence: "medium" — not high, and not dropped
EP12a call whose shape no signature in the plugin's vocabulary takes: a literal first argument, or no argument to a method that requires one (§5.4 item 1)null (EP5), whatever the receiver: the call stays in Symbol.calls[] and the file keeps its Symbols. Not EP3a — the candidate is well formed, so this is a classification decision, not an input-contract violation
EP13classify returns after running past classifyTimeoutMs (§5.1.1)its answer is used as if it had been fast — EP6 for a classification, EP5 for null, EP14 for a decline, and EP4 still decides the order — and the overrun is one stats.effectClassifyTimeouts entry. effects[], calls[] and the fingerprints do not depend on whether this classification overran its budget
EP14classify returns { declined: reason } (§4.5) and no later plugin classifies the callthe call stays in Symbol.calls[] (EP5), and stats.declinedCalls[] gains one entry: plugin, symbolId, target, line, and the reason. Neither effects[], calls[] nor any fingerprint differs from a null
EP14aa plugin declines a call and a later plugin classifies itthe later plugin's classification is used (EP6), and no stats.declinedCalls[] entry is written for that call
EP14bdeclined is empty, only whitespace, or not a stringthe run fails with scan-plugin-misconfigured, naming the plugin, whether or not a later plugin classifies the call
EP14cclassify returns an object carrying both effectId and declinedthe run fails with scan-plugin-misconfigured, naming the plugin, whatever the two values are

11. Design Decisions ​

11.1 Why effect plugins center on pure functions ​

The classify(call, ctx) → result shape:

  • Makes unit testing easy (no stateful test harness needed)
  • Is parallelizable (future performance improvements)
  • Never touches the AST directly, so it is unaffected by internal implementation changes in language plugins

To preserve the responsibility split of the whole extraction pipeline, effects stick strictly to "classification".

A decline (§4.5) is a return value, not a log line. A plugin could also report why it skipped a call through a Logger added to ClassifyContext, but three things count against it. Logging is a side effect that EP2 would have to allow. The line goes to a terminal, not to the IR that a reviewer, aburi diff and a CI job read. And the logger would be called inside the scan's innermost loop, once per call, within a 50ms budget. A returned reason keeps classify() pure, is stored in the IR next to the call it is about, and costs one small record, kept only when the call stays in calls[].

11.2 Choosing first-match-wins ​

Config order is a deterministic priority control: behavior is controlled with a single setting. Neither "complex consensus schemes" nor "weighted voting" needs to be introduced today.

If a user wants Prisma's db.write emitted as x-prisma:create, they place the Prisma plugin first.

11.3 Why effect plugins cannot write Symbol.derivedBy directly ​

Symbol.derivedBy[] is the evidence set for "why this Symbol appears in the IR in this form". An effect determination is evidence for a specific call, not for the Symbol as a whole, so the per-effect Effect.derivedBy (a single value) suffices.

For the use case of searching "Symbols that use Prisma" at the Symbol level, looking at Symbol.effects[] is enough.

11.4 Cross-language reuse ​

Prisma is used from TS and from Python alike (prisma-client-py). Because effect plugins are language-independent by design, a single plugin can recognize Prisma calls in both languages.

ClassifyContext.language is provided, so per-language behavior switches are also possible.

11.5 Why using owner.extKind is allowed ​

It enables context-dependent determinations such as "treat this.eventBus.publish(...) as event.publish only inside framework:nestjs:provider". owner.extKind has already been determined by the framework plugin (extraction order per lang-plugin §5.3).

11.6 Why literal analysis of SQL strings is included from the start ​

String-based ORMs like db.query("SELECT * FROM users WHERE id = ?") are common in real projects. Including literalArgs in CallCandidate makes analysis of string contents possible in a plugin, combined with an SQL parser library. The constraint of never accessing the AST stays intact; only the necessary information is added.

Released under the Apache License 2.0.