@filipebraida/adonis-function-points 0.1.0

package/build/resolvers-CU9HKYpn.js

@@ -0,0 +1,555 @@
+import { Node, SyntaxKind } from "ts-morph";
+//#region src/inventory/resolvers/action_object.ts
+/**
+* "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.
+*/
+const actionObjectResolver = {
+	name: "action-object",
+	order: 10,
+	resolve(call, ctx) {
+		const expr = call.getExpression();
+		if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) return [];
+		const member = expr.getName();
+		const className = classOfReceiver(expr.getExpression());
+		if (!className) return [];
+		const file = ctx.imports.get(className);
+		if (!file) return [];
+		return [{
+			file,
+			member
+		}];
+	}
+};
+/**
+* Finds the class behind a call receiver.
+*
+*   new Foo().handle()                    -> 'Foo'
+*   foo.handle()  where  const foo = new Foo()  -> 'Foo'
+*/
+function classOfReceiver(receiver) {
+	if (receiver.isKind(SyntaxKind.NewExpression)) {
+		const target = receiver.getExpression();
+		return target.isKind(SyntaxKind.Identifier) ? target.getText() : null;
+	}
+	if (receiver.isKind(SyntaxKind.Identifier)) {
+		const init = (receiver.getSymbol()?.getDeclarations().find((d) => d.isKind(SyntaxKind.VariableDeclaration)))?.asKind(SyntaxKind.VariableDeclaration)?.getInitializer();
+		if (init?.isKind(SyntaxKind.NewExpression)) {
+			const target = init.getExpression();
+			return target.isKind(SyntaxKind.Identifier) ? target.getText() : null;
+		}
+	}
+	return null;
+}
+//#endregion
+//#region src/inventory/resolvers/job_dispatch.ts
+const DISPATCH_METHODS = new Set([
+	"dispatch",
+	"dispatchLater",
+	"enqueue",
+	"later"
+]);
+/**
+* "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.
+*/
+const jobDispatchResolver = {
+	name: "job-dispatch",
+	order: 15,
+	resolve(call, ctx) {
+		const expr = call.getExpression();
+		if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) return [];
+		if (!DISPATCH_METHODS.has(expr.getName())) return [];
+		const receiver = expr.getExpression();
+		if (!receiver.isKind(SyntaxKind.Identifier)) return [];
+		const symbol = receiver.getText();
+		if (ctx.dataStoresBySymbol.has(symbol)) return [];
+		const file = ctx.imports.get(symbol);
+		if (!file) return [];
+		return [{
+			file,
+			member: ctx.sourceFile(file)?.getClasses().some((c) => c.getMethod("handle")) ? "handle" : expr.getName()
+		}];
+	}
+};
+//#endregion
+//#region src/inventory/resolvers/module_function.ts
+/**
+* "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.
+*/
+const moduleFunctionResolver = {
+	name: "module-function",
+	order: 50,
+	resolve(call, ctx) {
+		const expr = call.getExpression();
+		if (!expr.isKind(SyntaxKind.Identifier)) return [];
+		const file = ctx.imports.get(expr.getText());
+		if (!file) return [];
+		return [{
+			file,
+			member: expr.getText()
+		}];
+	}
+};
+//#endregion
+//#region src/inventory/resolvers/property_service.ts
+/**
+* "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.
+*/
+const propertyServiceResolver = {
+	name: "property-service",
+	order: 30,
+	resolve(call, ctx) {
+		const expression = call.getExpression();
+		if (!Node.isPropertyAccessExpression(expression)) return [];
+		const receiver = expression.getExpression();
+		if (!Node.isPropertyAccessExpression(receiver)) return [];
+		if (receiver.getExpression().getKind() !== SyntaxKind.ThisKeyword) return [];
+		const file = ctx.injected.get(receiver.getName());
+		if (!file) return [];
+		return [{
+			file,
+			member: expression.getName()
+		}];
+	}
+};
+//#endregion
+//#region src/inventory/resolvers/same_class_method.ts
+/**
+* "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`.
+*/
+const sameClassMethodResolver = {
+	name: "same-class-method",
+	order: 5,
+	resolve(call, ctx) {
+		const expression = call.getExpression();
+		if (!Node.isPropertyAccessExpression(expression)) return [];
+		if (expression.getExpression().getKind() !== SyntaxKind.ThisKeyword) return [];
+		const member = expression.getName();
+		const owner = call.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+		if (!owner) return [];
+		/**
+		* Only claim the call if the method really exists on the class. Otherwise
+		* `this.someFunctionProperty()` would be claimed, the body lookup would
+		* fail, and the report would blame inheritance from a package — sending the
+		* reader to the wrong place.
+		*/
+		if (!owner.getMethod(member) && !owner.getStaticMethod(member)) return [];
+		return [{
+			file: ctx.file.getFilePath(),
+			member
+		}];
+	}
+};
+//#endregion
+//#region src/inventory/resolvers/static_service.ts
+/**
+* "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.
+*/
+const staticServiceResolver = {
+	name: "static-service",
+	order: 20,
+	resolve(call, ctx) {
+		const expr = call.getExpression();
+		if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) return [];
+		const receiver = expr.getExpression();
+		if (!receiver.isKind(SyntaxKind.Identifier)) return [];
+		const symbol = receiver.getText();
+		if (ctx.dataStoresBySymbol.has(symbol)) return [];
+		const file = ctx.imports.get(symbol);
+		if (!file) return [];
+		return [{
+			file,
+			member: expr.getName()
+		}];
+	}
+};
+//#endregion
+//#region src/inventory/detectors/lucid.ts
+const WRITE_METHODS = new Set([
+	"save",
+	"delete",
+	"create",
+	"createMany",
+	"merge",
+	"fill",
+	"updateOrCreate",
+	"fetchOrCreateMany",
+	"firstOrCreate",
+	"updateOrCreateMany",
+	"attach",
+	"detach",
+	"sync",
+	"increment",
+	"decrement",
+	"update",
+	"truncate",
+	"restore",
+	"forceDelete"
+]);
+/**
+* Which hooks each access fires, by decorator name — counting-decisions §3.
+*
+* `save()` fires the save pair AND the create-or-update pair, and which of the
+* two runs is not knowable statically. That is not a compromise here: AFP
+* §6.5.3 requires treating multiple optional paths as part of the same
+* transaction, so following both is the specified behaviour.
+*/
+const HOOKS_BY_METHOD = {
+	save: [
+		"beforeSave",
+		"afterSave",
+		"beforeCreate",
+		"afterCreate",
+		"beforeUpdate",
+		"afterUpdate"
+	],
+	create: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeSave",
+		"afterSave"
+	],
+	createMany: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeSave",
+		"afterSave"
+	],
+	firstOrCreate: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeSave",
+		"afterSave"
+	],
+	fetchOrCreateMany: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeSave",
+		"afterSave"
+	],
+	updateOrCreate: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeUpdate",
+		"afterUpdate",
+		"beforeSave",
+		"afterSave"
+	],
+	updateOrCreateMany: [
+		"beforeCreate",
+		"afterCreate",
+		"beforeUpdate",
+		"afterUpdate",
+		"beforeSave",
+		"afterSave"
+	],
+	delete: ["beforeDelete", "afterDelete"],
+	forceDelete: ["beforeDelete", "afterDelete"],
+	find: ["beforeFind", "afterFind"],
+	findOrFail: ["beforeFind", "afterFind"],
+	findBy: ["beforeFind", "afterFind"],
+	findByOrFail: ["beforeFind", "afterFind"],
+	first: ["beforeFind", "afterFind"],
+	firstOrFail: ["beforeFind", "afterFind"],
+	all: ["beforeFetch", "afterFetch"],
+	findMany: ["beforeFetch", "afterFetch"]
+};
+new Set(Object.values(HOOKS_BY_METHOD).flat());
+/**
+* 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.
+*/
+function hooksFiredBy(access) {
+	if (!access.firesHooks) return [];
+	return HOOKS_BY_METHOD[access.method] ?? [];
+}
+const READ_METHODS = new Set([
+	"find",
+	"findOrFail",
+	"findBy",
+	"findByOrFail",
+	"findMany",
+	"first",
+	"firstOrFail",
+	"all",
+	"query",
+	"preload",
+	"load",
+	"paginate",
+	"count",
+	"exists",
+	"related",
+	"where",
+	"orderBy"
+]);
+function detectAccess(call, symbols, relations = /* @__PURE__ */ new Map()) {
+	const expression = call.getExpression();
+	if (!Node.isPropertyAccessExpression(expression)) return null;
+	const method = expression.getName();
+	const isWrite = WRITE_METHODS.has(method);
+	if (!isWrite && !READ_METHODS.has(method)) return null;
+	const receiver = expression.getExpression();
+	/**
+	* Looks up the PATH before the root: `input.invite.save()` has root `input`,
+	* which is no store at all — `input.invite` is.
+	*
+	* This is the dominant shape in action objects with a typed input, and
+	* without it the graph reaches the action and sees no write.
+	*/
+	const store = symbols.get(pathSymbolOf(receiver) ?? "") ?? symbols.get(rootSymbolOf(receiver) ?? "");
+	if (!store) return null;
+	return {
+		mode: isWrite ? "write" : "read",
+		store,
+		method,
+		line: call.getStartLineNumber(),
+		viaRelation: relationTargetOf(method, call, store, relations),
+		firesHooks: firesHooks(receiver)
+	};
+}
+/**
+* An access fires hooks unless it went through the query builder.
+*
+* The signal is a CALL anywhere in the receiver chain: `document.delete()` has
+* none, `Document.query().where(…).delete()` has two. It errs towards NOT
+* following — `(await Document.find(id))!.delete()` is read as bulk — because
+* an FTR that is missing understates, and one that is invented overstates.
+*/
+function firesHooks(receiver) {
+	let current = receiver;
+	for (let depth = 0; depth < 20; depth++) {
+		if (Node.isCallExpression(current)) return false;
+		if (!Node.isPropertyAccessExpression(current)) return Node.isIdentifier(current);
+		current = current.getExpression();
+	}
+	return false;
+}
+const RELATION_ACCESSORS = new Set([
+	"preload",
+	"load",
+	"related",
+	"withCount"
+]);
+/**
+* `.preload('author')` on a store declaring `{ author: 'Author' }` reaches
+* `Author`.
+*/
+function relationTargetOf(method, call, store, relations) {
+	if (!RELATION_ACCESSORS.has(method)) return void 0;
+	const name = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
+	if (!name) return void 0;
+	return relations.get(store)?.[name];
+}
+/**
+* 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.
+*/
+function pathSymbolOf(node) {
+	const parts = [];
+	let current = node;
+	for (let depth = 0; depth < 20; depth++) {
+		if (Node.isIdentifier(current)) return [current.getText(), ...parts].join(".");
+		if (!Node.isPropertyAccessExpression(current)) return null;
+		parts.unshift(current.getName());
+		current = current.getExpression();
+	}
+	return 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.
+*/
+function rootSymbolOf(node) {
+	let current = node;
+	for (let depth = 0; depth < 60 && current; depth++) {
+		if (Node.isIdentifier(current)) return current.getText();
+		if (current.getKind() === SyntaxKind.ThisKeyword) return "this";
+		if (Node.isPropertyAccessExpression(current) || Node.isElementAccessExpression(current) || Node.isCallExpression(current) || Node.isNewExpression(current) || Node.isAwaitExpression(current) || Node.isParenthesizedExpression(current) || Node.isNonNullExpression(current)) {
+			current = current.getExpression();
+			continue;
+		}
+		return null;
+	}
+	return null;
+}
+//#endregion
+//#region src/inventory/resolvers/transformer.ts
+/** BaseTransformer's public API; all of it funnels through `toObject` */
+const TRANSFORMER_METHODS = new Set([
+	"transform",
+	"paginate",
+	"toJSON",
+	"useVariant",
+	"withVariant"
+]);
+/** what the application-side body is called */
+const APPLICATION_BODY = "toObject";
+/**
+* "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.
+*/
+const transformerResolver = {
+	name: "transformer",
+	order: 18,
+	resolve(call, ctx) {
+		const expression = call.getExpression();
+		if (!Node.isPropertyAccessExpression(expression)) return [];
+		if (!TRANSFORMER_METHODS.has(expression.getName())) return [];
+		/**
+		* The root of the chain, so `X.transform(p).useVariant(v)` resolves as
+		* well as `X.transform(p)`. Analysing the same body twice is free: the
+		* graph dedupes by file and member.
+		*/
+		const symbol = rootSymbolOf(expression.getExpression());
+		if (!symbol) return [];
+		const file = ctx.imports.get(symbol) ?? ctx.injected.get(symbol);
+		if (!file) return [];
+		const declared = ctx.sourceFile(file);
+		if (!declared || !extendsTransformer(declared)) return [];
+		return declared.getClasses().find((cls) => cls.getMethod(APPLICATION_BODY)) ? [{
+			file,
+			member: APPLICATION_BODY
+		}] : [];
+	}
+};
+/**
+* Does a class here extend a transformer base from a package?
+*
+* Checked by the base's name and by its import being a bare specifier, so an
+* application class that merely happens to own a `transform` method is not
+* mistaken for one.
+*/
+function extendsTransformer(file) {
+	if (!file) return false;
+	for (const cls of file.getClasses()) {
+		const name = (cls.getExtends()?.getExpression())?.asKind(SyntaxKind.Identifier)?.getText();
+		if (!name?.endsWith("Transformer")) continue;
+		const imported = file.getImportDeclarations().find((declaration) => declaration.getNamedImports().some((named) => named.getName() === name));
+		if (imported && !imported.getModuleSpecifierValue().startsWith("#")) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/inventory/resolvers/index.ts
+/**
+* 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.
+*/
+const BUILTIN_CALL_RESOLVERS = [
+	sameClassMethodResolver,
+	actionObjectResolver,
+	jobDispatchResolver,
+	transformerResolver,
+	staticServiceResolver,
+	propertyServiceResolver,
+	moduleFunctionResolver
+];
+/**
+* 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.
+*/
+function resolveCall(call, ctx, resolvers = BUILTIN_CALL_RESOLVERS) {
+	for (const resolver of resolvers) {
+		const refs = resolver.resolve(call, ctx);
+		if (refs.length > 0) return {
+			by: resolver.name,
+			refs
+		};
+	}
+	return null;
+}
+//#endregion
+export { rootSymbolOf as a, hooksFiredBy as i, resolveCall as n, detectAccess as r, BUILTIN_CALL_RESOLVERS as t };