@filipebraida/adonis-function-points 0.1.0

package/build/src/define_config.d.ts

@@ -0,0 +1,137 @@
+import type { ComplexityTable } from './albrecht/tables.js';
+import type { CallResolver } from './inventory/resolvers/types.js';
+import type { Complexity, FunctionType } from './types.js';
+/**
+ * Package configuration.
+ *
+ * **Every option here has an effect, and a test proving it.** Configuration the
+ * code does not honour is worse than no configuration at all: whoever sets it
+ * believes something changed when nothing did, and the number goes into an
+ * invoice.
+ *
+ * That is why the list is short. What remains configurable is what is a
+ * **business decision** that no heuristic should make — the application
+ * boundary, what is maintained externally, the calibrated complexity bands.
+ * The rest the package discovers.
+ */
+export type FunctionPointsConfig = {
+    /**
+     * The application boundary. A business decision, not a technical one — review
+     * it with whoever signs the contract, not only with the team.
+     */
+    boundary: {
+        /**
+         * Infrastructure stores, excluded from the count: session tokens, audit
+         * trails, queues, caches.
+         *
+         * Complements the automatic technical-data filter (AFP §6.5.2.1.1), which
+         * already catches session, error, search and template names. Exclusions
+         * made here also appear in the report, with the reason.
+         */
+        infrastructure?: string[];
+        /**
+         * Stores maintained by another system: counted as EIF instead of ILF.
+         *
+         * For example, tables mirrored from an external ERP.
+         */
+        externallyMaintained?: string[];
+        /**
+         * Entry points with no functional value to the user, by route name or by
+         * identity (`GET /health`).
+         *
+         * Rarely needed in practice: an infrastructure route reaches no data store
+         * and already drops out. It stays as a safety net and to make the intent
+         * explicit in the report.
+         */
+        ignoreEntryPoints?: string[];
+    };
+    /**
+     * Strategy for RET, the logical subgroups of an ILF/EIF.
+     *
+     * `constant` pins it at 1, which is honest: what a user recognises as a
+     * subgroup is not derivable from code. `composition` derives it from
+     * composition relations; less accurate in general, but captures real
+     * aggregates.
+     */
+    retStrategy: 'constant' | 'composition';
+    /**
+     * Maximum depth in the call graph, starting at the handler.
+     *
+     * Too deep and a large shared service contaminates its callers; too shallow
+     * and the write is missed.
+     */
+    maxDepth: number;
+    /**
+     * Extra DET for the confirmation or error message.
+     *
+     * The IFPUG manual counts one, AFP does not — a known systematic divergence
+     * of −1 DET per transaction against manual counts. The default follows AFP.
+     */
+    messageDet: number;
+    /** Complexity bands, for calibrating against manual counts. */
+    complexityTables?: Partial<Record<FunctionType, ComplexityTable>>;
+    /** Weights per type and complexity. */
+    weights?: Partial<Record<FunctionType, Record<Complexity, number>>>;
+    /**
+     * Custom tracing strategies, added to the built-in ones and running
+     * **before** them.
+     *
+     * This is what makes the architecture's central claim true: AdonisJS imposes
+     * no code organisation, so a project with its own convention registers it
+     * here.
+     */
+    resolvers?: {
+        call?: CallResolver[];
+    };
+    /**
+     * Minimum tracing coverage, from 0 to 1.
+     *
+     * Below it the analysis **fails** instead of emitting a number that looks
+     * right. A total resting on many unresolved calls should not become an
+     * invoice.
+     */
+    minCoverage?: number;
+    /**
+     * Declared DET or RET/FTR for a function the analysis cannot read, keyed by
+     * the name it has in the count (`Petition`, `POST /books`).
+     *
+     * The case this exists for is a schema-driven application: when the fields a
+     * user fills live in a JSON column whose schema is stored in the database,
+     * there is nothing for static analysis to read and the column counts as 1 DET
+     * (counting-decisions §8). The person who knows the form knows the number.
+     *
+     * `reason` is required, and that is the whole point. A declared number is
+     * reproducible — it lives in a versioned file, so the same revision yields
+     * the same count — and auditable, because `fp:explain` prints it with its
+     * justification. A number the tool guessed would be neither.
+     *
+     * Use sparingly. If overriding becomes a habit the count stops coming from
+     * the code, and the report says how much of the total came from here so that
+     * cannot grow unnoticed.
+     */
+    overrides?: Record<string, FunctionOverride>;
+};
+export type FunctionOverride = {
+    /** declared DET count, replacing what the analysis found */
+    det?: number;
+    /**
+     * Name of a JSON Schema declared in the application's code, whose fields are
+     * counted by the §7 leaf rules and replace the single DET the opaque column
+     * contributed.
+     *
+     * Prefer this to `det`. A declared number freezes: someone adds a field, the
+     * count does not move, and `fp:diff` reports no change for real functional
+     * growth — undercounting silently and progressively. Naming the schema keeps
+     * the number coming from the code; the only thing maintained by hand is the
+     * mapping, which changes when a form is born rather than when a field is.
+     *
+     * A name that matches no schema is a warning, never a silent fallback.
+     */
+    detFromSchema?: string;
+    /** declared RET (data function) or FTR (transaction) */
+    refs?: number;
+    /** why — required, and printed by `fp:explain` beside the number */
+    reason: string;
+};
+export declare const DEFAULTS: FunctionPointsConfig;
+export declare function defineConfig(config: Partial<FunctionPointsConfig>): FunctionPointsConfig;

package/build/src/inventory/app_context.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Discovers the shape of the analysed application instead of assuming a
+ * convention.
+ *
+ * Folder layout, subpath aliases and model style all vary between AdonisJS
+ * applications. What does not vary is that the facts are discoverable — which
+ * is why this package needs almost no configuration.
+ */
+export type AppLayout = 'flat' | 'module-per-domain' | 'unknown';
+export type AppContext = {
+    /** application root (where adonisrc.ts lives) */
+    root: string;
+    /**
+     * The package.json `imports` map, normalised.
+     *
+     * It must be READ, never inferred: two incompatible conventions are in use —
+     * by artefact type (`#models/*`) and by domain module (`#catalog/*`).
+     */
+    subpathImports: Map<string, string>;
+    /**
+     * Generated artefacts found.
+     *
+     * Absence is a reportable fact, not something to work around silently:
+     * without the registry the count falls back to the route parser, which is
+     * less precise, and the report must say so.
+     */
+    generated: {
+        routeRegistry?: string;
+        controllersMap?: string;
+        dataSchema?: string;
+    };
+    /** detected; used to GROUP the report, never to find files */
+    layout: AppLayout;
+    /**
+     * Files that register routes, starting from the adonisrc `preloads` and
+     * following the static imports they reach.
+     *
+     * The preload list is the authoritative source, not a path convention. Four
+     * topologies occur in practice: a single file, one per module, a directory,
+     * and a hub that only re-exports.
+     */
+    routeFiles: string[];
+    /**
+     * Directories to scan, derived from the alias targets.
+     *
+     * Not simply `app/`: applications exist where all writes live under `src/`.
+     * Roots nested inside other roots are collapsed.
+     */
+    scanRoots: string[];
+    /** versions and ORM — they pick the strategy and go into the report */
+    framework: FrameworkInfo;
+    /** `#catalog/models/book` -> absolute path, or null */
+    resolveSpecifier(specifier: string): string | null;
+    /** module a file belongs to, for grouping the report */
+    moduleOf(absPath: string): string;
+};
+export type FrameworkInfo = {
+    /** major of @adonisjs/core, when declared */
+    core?: number;
+    /** major of @adonisjs/lucid, when declared */
+    lucid?: number;
+    orm: 'lucid' | 'kysely' | 'unknown';
+    /** Tuyau provides typed input DETs; optional */
+    tuyau: boolean;
+    /**
+     * Within the v1 scope (core 7 + Lucid 22).
+     *
+     * Outside it the package reports instead of counting — counting wrong in
+     * silence is the worst possible failure for a number that becomes an invoice.
+     */
+    supported: boolean;
+};
+export declare function discoverApp(root: string): Promise<AppContext>;

package/build/src/inventory/detectors/lucid.d.ts

@@ -0,0 +1,77 @@
+import { Node } from 'ts-morph';
+import type { CallExpression } from 'ts-morph';
+/**
+ * Recognises Lucid data access at a call site.
+ *
+ * **Call-site level, never file level.** A large domain service can hold dozens
+ * of writes; asking "does this file contain a write?" would mark every importer
+ * as a writer.
+ *
+ * False positives deliberately avoided here:
+ *
+ *   `.related('x')`   a relation accessor, used both to read and to write — it
+ *                     only counts when it ends in attach/detach/sync/save/create
+ *   `.create(`        also appears in `vine.create(` and various builders; it
+ *                     only counts when the receiver resolves to a known store
+ *   `invite.save()`   a lower-case instance does not match the model name under
+ *                     textual comparison — hence the symbol map
+ */
+export type AccessMode = 'read' | 'write';
+export type PersistenceAccess = {
+    mode: AccessMode;
+    /** id of the data store reached */
+    store: string;
+    method: string;
+    line: number;
+    /**
+     * Store reached through a RELATION rather than directly.
+     *
+     * `Book.query().preload('author')` reads the authors table. Under AFP that is
+     * an FTR on `Author`, and ignoring it would drop a table read only through a
+     * relation out of the count (§6.5.4) when it is a legitimate EIF.
+     */
+    viaRelation?: string;
+    /**
+     * Does this access fire the model's hooks?
+     *
+     * Lucid fires instance hooks for `document.delete()` and does NOT fire them
+     * for `Document.query().where(…).delete()` — both of which land on
+     * `method === 'delete'`. Following hooks for the bulk form would invent an
+     * FTR, and counting more than is there is worse than counting less: an
+     * invented FTR moves a complexity band and goes onto an invoice.
+     */
+    firesHooks: boolean;
+};
+/** decorators this package knows how to follow */
+export declare const HOOK_DECORATORS: Set<string>;
+/**
+ * Hook decorators fired by an access, or `[]` when it fires none.
+ *
+ * `truncate`, `increment`, `decrement` and the pivot operations change rows
+ * without instantiating a model, so no hook runs.
+ */
+export declare function hooksFiredBy(access: PersistenceAccess): string[];
+/**
+ * Symbols that resolve to a data store within a body's scope.
+ *
+ * Includes the model name (`Invite`) and local variables derived from it
+ * (`const invite = await Invite.findOrFail(...)`).
+ */
+export type StoreSymbols = Map<string, string>;
+/** store -> its declared relations */
+export type RelationMap = Map<string, Record<string, string>>;
+export declare function detectAccess(call: CallExpression, symbols: StoreSymbols, relations?: RelationMap): PersistenceAccess | null;
+/**
+ * Dotted path of a receiver made only of property accesses: `input.invite`
+ * yields "input.invite". Any call in between invalidates the path, because the
+ * value stops being statically traceable.
+ */
+export declare function pathSymbolOf(node: Node): string | null;
+/**
+ * Root of an `a.b().c()` chain — the left-most identifier.
+ *
+ * It must traverse `await`, calls, property access and `new`, otherwise
+ * `await new Action().handle()` and `Invite.query().where().update()` stop at
+ * the first node and the write disappears.
+ */
+export declare function rootSymbolOf(node: Node): string | null;

package/build/src/inventory/graph/call_graph.d.ts

@@ -0,0 +1,80 @@
+import type { ClassDeclaration, SourceFile } from 'ts-morph';
+import type { AppContext } from '../app_context.js';
+import type { CollectedDataStore } from '../sources/data_stores.js';
+import type { CallResolver } from '../resolvers/types.js';
+import type { HandlerRef, TraceStep, UnresolvedCall } from '../../types.js';
+/**
+ * The transaction → data function graph. It is the backbone of the count.
+ *
+ * Three of the four boundary decisions are settled here: a static route does
+ * not count because it reaches no data; a route from a package likewise; a
+ * model hook counts because it lies on the path. And AFP requires aggregating
+ * ALL reachable paths:
+ *
+ *   "When the static code analyzer finds multiple optional paths in the context
+ *    of a transaction, it shall consider these multiple optional paths to be
+ *    part of the same transaction."  — AFP §6.5.3
+ *
+ * Traversal is at METHOD level, never at file level: a domain service holds
+ * many writes, and asking about the file would mark everyone importing it as a
+ * writer.
+ */
+export type ScopeEntry = {
+    file: string;
+    member?: string;
+    /** hash of the normalised AST — counting-decisions §5 */
+    bodyHash: string;
+};
+export type Behavior = {
+    writes: boolean;
+    /** data stores reached */
+    touches: string[];
+    /**
+     * Declared input fields: `request.validateUsing(x)` resolved down to the
+     * fields of the VineJS schema — counting-decisions §7.
+     */
+    inputFields: string[];
+    trace: TraceStep[];
+    /** bodies reached, for `fp:diff` */
+    scope: ScopeEntry[];
+    unresolved: UnresolvedCall[];
+};
+export type GraphOptions = {
+    /** how far to follow from the handler; the default comes from configuration */
+    maxDepth?: number;
+    /**
+     * Custom strategies, added to the built-in ones and ordered by `order`.
+     *
+     * This is what makes tracing extensible: AdonisJS imposes no organisation
+     * pattern, so a project with its own convention registers it here.
+     */
+    callResolvers?: CallResolver[];
+};
+/**
+ * Analyzer with state shared across handlers.
+ *
+ * The ts-morph `Project` and the symbol cache are expensive to build and
+ * identical for every handler of the same application. Creating one per handler
+ * multiplies the cost by the number of routes, which is the difference between
+ * minutes and seconds on an application of a few hundred routes.
+ */
+export declare function createAnalyzer(app: AppContext, stores: CollectedDataStore[], options?: GraphOptions): {
+    analyze: (handler: HandlerRef) => Behavior;
+    /** how many files the project loaded — used to prove it does not grow */
+    fileCount: () => number;
+};
+/** Convenience for a single handler; for several, use `createAnalyzer`. */
+export declare function analyzeHandler(app: AppContext, stores: CollectedDataStore[], handler: HandlerRef, options?: GraphOptions): Behavior;
+/**
+ * Injected dependencies visible in the body: property name -> file.
+ *
+ * Two forms, both with the type annotated explicitly — `@inject()` does not
+ * work without it:
+ *
+ *   constructor(protected billing: BillingService) {}
+ *   private declare billing: BillingService
+ *
+ * Since the type is an imported identifier, it resolves through the same path
+ * as any import. No type checker is needed.
+ */
+export declare function injectedFor(owner: ClassDeclaration | undefined, file: SourceFile, app: AppContext): Map<string, string>;

package/build/src/inventory/graph/noise.d.ts

@@ -0,0 +1,9 @@
+import type { CallExpression, ClassDeclaration } from 'ts-morph';
+/** Is this call one that cannot reach a data store? */
+export declare function isNoise(call: CallExpression, owner?: ClassDeclaration): boolean;
+/**
+ * The body-not-found path: a symbol resolved to an application file whose
+ * member is not there. For a framework service that is expected — the
+ * implementation is in the package — and says nothing about tracing quality.
+ */
+export declare function isNoiseMember(file: string, member?: string): boolean;

package/build/src/inventory/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Inventory layer: extracts raw facts from the application.
+ *
+ * ARCHITECTURAL RULE: nothing here imports from `src/albrecht/**`. The
+ * inventory does not know what an ILF is. That separation is what would allow
+ * extracting this layer into its own package if the structural metrics grow.
+ *
+ * SOURCE PRECEDENCE, most to least reliable:
+ *   1. generated artefacts — route registry, generated data schema
+ *   2. runtime            — router.toJSON(), Lucid metadata
+ *   3. AST                — call graph, write detection
+ *   4. folder convention  — report grouping only, never for finding things
+ */
+export * from './resolvers/index.js';
+export type { AppContext } from './app_context.js';

package/build/src/inventory/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One canonical spelling for every path the inventory emits.
+ *
+ * Two path styles meet in this package. ts-morph always returns forward
+ * slashes, including on Windows; node's `path.join` returns backslashes there.
+ * Both end up in `HandlerRef.file`, and the call graph uses that string as a
+ * cache key:
+ *
+ *     const key = `${ref.file}#${ref.member ?? ref.line ?? '*'}`
+ *
+ * Two spellings of the same file are two keys, so the same body would be
+ * analysed twice and pushed twice into the trace and the implementation scope
+ * — and a repeated scope entry changes the hash `fp:diff` compares.
+ *
+ * Forward slashes win because ts-morph cannot be told otherwise, node's `fs`
+ * accepts them on Windows, and `path.relative` normalises mixed input anyway.
+ * Normalising at the boundary where a path is created costs one call; leaving
+ * it to each comparison costs vigilance forever.
+ */
+export declare const toPosix: (value: string) => string;
+/** Compares two paths that may have come from different sources. */
+export declare const samePath: (a: string | undefined, b: string | undefined) => boolean;

package/build/src/inventory/resolvers/action_object.d.ts

@@ -0,0 +1,14 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Action object" pattern: the transaction delegates to an action instantiated
+ * at the call site.
+ *
+ *     await new ExpireInvite().handle({ invite })
+ *
+ *     const mark = new MarkContentChanged()
+ *     await mark.handle({ documentId })
+ *
+ * The second form keeps the instance in a local variable, so the declaration
+ * has to be followed back to the `new` — that is what `classOfReceiver` does.
+ */
+export declare const actionObjectResolver: CallResolver;

package/build/src/inventory/resolvers/index.d.ts

@@ -0,0 +1,23 @@
+import type { CallResolver } from './types.js';
+export * from './types.js';
+/**
+ * Built-in strategies, ordered from most to least specific.
+ *
+ * They cover the patterns that appear in real AdonisJS applications. No closed
+ * list can cover them all — a project with its own convention registers it in
+ * `config/function_points.ts`, and it runs before these.
+ */
+export declare const BUILTIN_CALL_RESOLVERS: CallResolver[];
+/**
+ * The FIRST strategy that claims a call wins.
+ *
+ * This is not an implementation detail: syntactically identical shapes carry
+ * different meanings. `CreateUserJob.dispatch(p)`, `UserService.create(p)` and
+ * `User.find(p)` are all `Identifier.method(args)`, and only ordering tells
+ * them apart. Hence specific strategies declare a lower `order` than generic
+ * ones, and `module-function` comes last — it would match almost anything.
+ */
+export declare function resolveCall(call: import('ts-morph').CallExpression, ctx: import('./types.js').ResolverContext, resolvers?: CallResolver[]): {
+    by: string;
+    refs: import('../../types.js').HandlerRef[];
+} | null;

package/build/src/inventory/resolvers/index.js

@@ -0,0 +1,2 @@
+import { n as resolveCall, t as BUILTIN_CALL_RESOLVERS } from "../../../resolvers-CU9HKYpn.js";
+export { BUILTIN_CALL_RESOLVERS, resolveCall };

package/build/src/inventory/resolvers/job_dispatch.d.ts

@@ -0,0 +1,18 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Job" pattern: the write happens asynchronously.
+ *
+ *     await CreateUserJob.dispatch({ userId })
+ *
+ * Runs before `static-service` on purpose: the syntactic shape is identical
+ * (`Identifier.method(args)`) and the generic strategy would swallow the job.
+ * The distinction is semantic, and it matters because the counting decision
+ * differs.
+ *
+ * COUNTING DECISION: a job dispatched by a handler is followed as part of the
+ * SAME transactional function, because IFPUG counts what the user recognises —
+ * they click and the effect happens, even if execution is asynchronous. A
+ * SCHEDULED job, which nobody dispatches, is a different thing: it is an entry
+ * point of its own, and out of v1 scope — only HTTP routes are collected.
+ */
+export declare const jobDispatchResolver: CallResolver;

package/build/src/inventory/resolvers/module_function.d.ts

@@ -0,0 +1,11 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Module function" pattern: no class at all.
+ *
+ *     await createUser(payload)
+ *     await syncWithProvider(order)
+ *
+ * Runs last: it matches any call to an imported identifier and would otherwise
+ * swallow the more precise patterns.
+ */
+export declare const moduleFunctionResolver: CallResolver;

package/build/src/inventory/resolvers/property_service.d.ts

@@ -0,0 +1,18 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Injected dependency" pattern: the call leaves through a class property.
+ *
+ *     @inject()
+ *     class InvoiceController {
+ *       constructor(protected billing: BillingService) {}
+ *       async queue() { await this.billing.enqueue(invoice) }
+ *     }
+ *
+ * This is the official AdonisJS pattern, and in applications that use it, it is
+ * frequently the only path from a route down to a write.
+ *
+ * **No type checker required.** `@inject()` only works with an explicit type
+ * annotation — that annotation is how the container knows what to inject — so
+ * the type is always in the AST as an imported identifier.
+ */
+export declare const propertyServiceResolver: CallResolver;

package/build/src/inventory/resolvers/same_class_method.d.ts

@@ -0,0 +1,17 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Same class method" pattern: `this.privateMethod()`.
+ *
+ *     async expire(uuid: string) {
+ *       const invite = await this.findByUuid(uuid)
+ *       await this.persistExpiration(invite)
+ *     }
+ *
+ * A public method delegating to private ones of the same class is where writes
+ * often live. No other strategy covers it — `property-service` requires
+ * `this.dependency.method()`, with two levels of access.
+ *
+ * Runs before `property-service` because it is more specific: the receiver is
+ * exactly `this`.
+ */
+export declare const sameClassMethodResolver: CallResolver;

package/build/src/inventory/resolvers/static_service.d.ts

@@ -0,0 +1,13 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Static service" pattern: a class method called without instantiating.
+ *
+ *     await UserService.create(payload)
+ *     await OrderService.finalize(order)
+ *
+ * Careful: `Order.findByOrFail(...)` has exactly the same syntactic shape. The
+ * difference is semantic — a model is a data store, not a body to walk into,
+ * and the persistence detector handles it. Hence this resolver depends on
+ * `ctx.dataStoresBySymbol` already being populated.
+ */
+export declare const staticServiceResolver: CallResolver;

package/build/src/inventory/resolvers/transformer.d.ts

@@ -0,0 +1,25 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Transformer" pattern: the package supplies the API, the application
+ * supplies the body.
+ *
+ *     class InviteTransformer extends BaseTransformer<Invite> {
+ *       toObject() { … }
+ *     }
+ *
+ *     InviteTransformer.transform(invite)
+ *
+ * `transform()` and `paginate()` live in `@adonisjs/core`, so resolving the
+ * symbol lands on the application file and finds no body there. The naive
+ * reading is that the tracer must step into node_modules; it does not. Those
+ * methods call BACK into `toObject()`, which the application writes, so the
+ * body worth analysing was in the application all along.
+ *
+ * It is the same shape as `job-dispatch`, where `dispatch` enqueues and
+ * `handle` executes.
+ *
+ * COUNTING DECISION: the write a transformer performs belongs to the
+ * transaction that serialised through it. Without this, a table written only
+ * inside `toObject()` is reached by nobody and drops out under AFP §6.5.4.
+ */
+export declare const transformerResolver: CallResolver;

package/build/src/inventory/resolvers/types.d.ts

@@ -0,0 +1,65 @@
+import type { CallExpression, SourceFile } from 'ts-morph';
+import type { DataStore, HandlerRef } from '../../types.js';
+/**
+ * AdonisJS does not impose a code organisation. The same transaction can be
+ * written in very different ways:
+ *
+ *   fat controller      await User.create(payload)
+ *   action object       await new CreateUser().handle(payload)
+ *   static service      await UserService.create(payload)
+ *   injected service    await this.users.create(payload)
+ *   repository          await this.repo.persist(user)
+ *   job                 await CreateUserJob.dispatch(payload)
+ *   query builder       await db.table('users').insert(payload)
+ *
+ * No closed list covers that. Tracing is therefore assembled from registrable
+ * strategies, and whatever none of them resolves is REPORTED — never silently
+ * treated as a read.
+ *
+ * That is the most important contract in the package: saying "I don't know" is
+ * preferable to producing a number that looks right.
+ */
+export type ResolverContext = {
+    /** file containing the call site */
+    file: SourceFile;
+    /** current depth in the call graph */
+    depth: number;
+    /** file imports: local identifier -> resolved absolute path */
+    imports: Map<string, string>;
+    /**
+     * Injected dependencies visible in this body: property name -> class file.
+     * For example `billing` -> `.../billing_service.ts`.
+     *
+     * No type checker needed: AdonisJS `@inject()` **requires** an explicit type
+     * annotation for the container to resolve the dependency, so
+     * `constructor(protected billing: BillingService)` always carries the
+     * type as an identifier — imported like any other.
+     */
+    injected: Map<string, string>;
+    /**
+     * Known data stores, keyed by symbol name (e.g. 'User').
+     *
+     * ORDERING INVARIANT: data stores are collected BEFORE any handler analysis.
+     * Without that, `UserService.create()` and `User.create()` are
+     * indistinguishable by shape, and a resolver would walk into the model as if
+     * it were business code.
+     */
+    dataStoresBySymbol: Map<string, DataStore>;
+    /** resolves an AdonisJS specifier (`#collect/models/invite`) to a path */
+    resolveSpecifier(specifier: string): string | null;
+    /** loads a file into the project, if it exists */
+    sourceFile(absPath: string): SourceFile | null;
+};
+/**
+ * Follows a call site to the next body to analyse.
+ *
+ * Returns `[]` when the strategy does not recognise the call — that is not an
+ * error, another strategy may recognise it. Only when none does should the call
+ * land in `unresolved`.
+ */
+export interface CallResolver {
+    readonly name: string;
+    /** lower runs first; specific strategies before generic ones */
+    readonly order?: number;
+    resolve(call: CallExpression, ctx: ResolverContext): HandlerRef[];
+}