@filipebraida/adonis-function-points 0.6.0 → 0.8.0

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

@@ -0,0 +1,94 @@
+import { Node } from 'ts-morph';
+import type { CallExpression, SourceFile } from 'ts-morph';
+import type { RelationMap, StoreSymbols } from '../detectors/lucid.js';
+import type { PageRef } from './pages.js';
+import type { HandlerRef } from '../../types.js';
+/**
+ * What a transaction DELIVERS — counting-decisions §6, plan 0.7 §A′.
+ *
+ * The DETs of an output are the fields that cross the boundary, and the place
+ * they cross is the delivery: the props handed to `inertia.render` /
+ * `inertia.modal` / `view.render`, the payload of `response.json|ok|created|send`,
+ * a literal the handler returns. Before this, "what leaves" was every column of
+ * every store the transaction touched — a `findOrFail` made to authorise handed
+ * the whole table to the screen, and a derived `total` handed nothing.
+ *
+ * Measured on three applications first: no delivered collection is a variable
+ * bound to a store; they come out of query objects the graph already follows.
+ * So a delivered value that comes from a followed call is resolved to what that
+ * body returns — the graph does that in `run()`, once the bodies are known; this
+ * module only says WHAT was delivered and where it came from.
+ */
+export type Delivery = DeliveredValue & {
+    /** the page or template this value was handed to, when it was a render — what the page shows of it is read there */
+    via?: PageRef;
+};
+type DeliveredValue = 
+/** a variable bound to a store: its columns leave */
+{
+    kind: 'store';
+    store: string;
+    path: string;
+}
+/**
+ * The result of a call a strategy followed: what that body returns leaves.
+ * `args` are the call's arguments, classified — a body that returns no literal
+ * and reads no store (a CSV builder) delivers what was handed INTO it.
+ */
+ | {
+    kind: 'call';
+    refs: HandlerRef[];
+    path: string;
+    expression: string;
+    args: Delivery[];
+    /**
+     * One key of what the call returns — `const { data } = await q.handle()`,
+     * `relatorio.linhas` — rather than the whole result. Resolved against the
+     * body's classified return, keeping only that key.
+     */
+    pick?: string;
+}
+/** a scalar, a property, an expression: one DET */
+ | {
+    kind: 'scalar';
+    path: string;
+}
+/** an input echoed back — the validated payload, a field read off the request: counts once, on entry */
+ | {
+    kind: 'echo';
+    path: string;
+}
+/** something the classifier cannot read: one DET as a floor, reported */
+ | {
+    kind: 'opaque';
+    path: string;
+    expression: string;
+};
+/** keys of a result that carry its rows: picking one of these is not picking one value */
+export declare const PASSES_ROWS: Set<string>;
+export type DeliveryContext = {
+    body: Node;
+    file: SourceFile;
+    symbols: StoreSymbols;
+    relations: RelationMap;
+    followed: Map<CallExpression, HandlerRef[]>;
+};
+export type BodyDeliveries = {
+    /** props handed to a renderer or a response method, anywhere in the body */
+    calls: Delivery[];
+    /** a delivery call was found, even with nothing readable in it */
+    anyCall: boolean;
+    /**
+     * What a `return` hands back that is not one of those calls — meaningful for
+     * the ENTRY body only, where returning a value is delivering it; a followed
+     * body's return is read by `returnedLeavesOf` instead.
+     */
+    returns: Delivery[];
+    anyReturn: boolean;
+};
+/**
+ * The deliveries of a body: every props argument handed to a renderer or a
+ * response method, and what a `return` hands back that is not one of those calls.
+ */
+export declare function deliveriesIn(ctx: DeliveryContext): BodyDeliveries;
+export {};

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

@@ -1,5 +1,5 @@
 import { Node } from 'ts-morph';
-import type { CallExpression, ClassDeclaration } from 'ts-morph';
+import type { CallExpression, ClassDeclaration, Expression, ObjectLiteralExpression } from 'ts-morph';
 import type { CollectedDataStore } from '../sources/data_stores.js';
 /**
  * What an output transaction actually EMITS — counting-decisions §6.
@@ -77,6 +77,49 @@ export declare function transformerResourceOf(cls: ClassDeclaration): string | n
  * the same reason `isPrimary` is not one on the data function.
  */
 export declare function outputFieldsIn(body: Node, owner: ClassDeclaration | undefined, stores: Map<string, CollectedDataStore>, followed: (call: CallExpression) => boolean): OutputFacts;
+/**
+ * The leaves of the object literal ANY body returns — a query object building a
+ * summary, a module function assembling a view model. Same walker as the
+ * transformer's, unqualified: the caller prefixes the path the value was
+ * delivered under. `null` when the body returns no literal.
+ */
+export declare function returnedLeavesOf(body: Node, followed: (call: CallExpression) => boolean): {
+    leaves: string[];
+    opaque: string[];
+} | null;
+type LeafOptions = {
+    /** prefixed to every leaf, with a dot; empty for an unqualified walk */
+    qualifier: string;
+    /** top-level names that are not DETs (the resource's key, its stamps) */
+    excluded: Set<string>;
+    followed: (call: CallExpression) => boolean;
+};
+/**
+ * The leaves of object literals, by the §7 rules:
+ *
+ *   { titulo: l.titulo }                 1 — `titulo`
+ *   { autor: AutorTransformer.transform } 0 here; the followed body contributes
+ *   { endereco: { rua, cidade } }        leaves individually
+ *   { tags: xs.map((t) => t.nome) }      1 — a repeating group of one attribute
+ *   { itens: xs.map((i) => ({ a, b })) } the leaves, once
+ *   ...this.pick(this.resource, [...])   the listed names
+ *   ...this.toObject()                   0 here; the followed body contributes
+ *   ...anythingElse                      1, opaque, reported
+ */
+export declare function collectLeaves(literals: ObjectLiteralExpression[], options: LeafOptions): {
+    leaves: string[];
+    opaque: string[];
+};
+/**
+ * Object literals the body itself returns — not the ones returned by arrow
+ * functions inside it, which belong to `.map()` callbacks and are read as
+ * repeating groups where they occur.
+ */
+export declare function returnedLiteralsOf(body: Node): ObjectLiteralExpression[];
+/** `xs.map((x) => ({ a, b }))` -> the literal; null for a scalar map or anything else */
+export declare function mappedLiteralOf(value: Expression): ObjectLiteralExpression | null;
+/** strips parentheses, `as`, `satisfies` and non-null assertions */
+export declare function unwrap(node: Node | undefined | null): Expression | null;
 /**
  * The shape of the chain an access belongs to — read from the WHOLE chain, root
  * to end, because every call on it is detected as an access and each must reach
@@ -97,3 +140,4 @@ export type ChainShape = {
     }[];
 };
 export declare function chainShapeOf(access: CallExpression): ChainShape;
+export {};

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

@@ -0,0 +1,44 @@
+import type { Project } from 'ts-morph';
+import type { RelationMap } from '../detectors/lucid.js';
+import type { CollectedDataStore } from '../sources/data_stores.js';
+/**
+ * What the page SHOWS of a store handed to it raw — plan 0.7 §B / 0.8 §D,
+ * counting-decisions §6.
+ *
+ * The delivery rule (§A′) says which store leaves; a transformer or a `.select()`
+ * says which columns. With neither, the store left whole — and the CPM defines an
+ * output's DETs by what the user sees. The page is TypeScript (`.tsx`) or Edge,
+ * and the same reader that opened the controller can open it: from the
+ * component's props to every member read off a row, one child component deep.
+ *
+ * Where it cannot read — a second level of components, a spread, a package's
+ * component, two files answering to one page name — the store leaves whole and
+ * the transaction is REPORTED with the reason. Overestimating in the open, never a
+ * floor: a floor would undercount what the user sees.
+ */
+export type PageRef = {
+    engine: 'inertia' | 'edge';
+    page: string;
+};
+/** a store handed raw to a page, at a key path of its props (`vagas.data`) */
+export type RawDelivery = PageRef & {
+    store: string;
+    path: string;
+};
+export type PageReading = {
+    /** store -> columns the page reads off its rows */
+    columns: Map<string, Set<string>>;
+    /** store -> why the page could not be read for it (the store then leaves whole) */
+    unreadable: Map<string, string>;
+    /** store -> members the page reads that are NOT its columns (`inventor.nomeCompleto`, computed on the way) */
+    unknownMembers: Map<string, Set<string>>;
+};
+export type PageEnvironment = {
+    root: string;
+    project: Project;
+    stores: Map<string, CollectedDataStore>;
+    relations: RelationMap;
+    /** the application's subpath imports (`#tecnologias/ui/components/x`), as the graph resolves them */
+    resolveSpecifier: (specifier: string) => string | null;
+};
+export declare function readPages(deliveries: RawDelivery[], env: PageEnvironment): PageReading;

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

@@ -1,2 +1,2 @@
-import { i as resolveCall, n as ignoreCalls, r as isTechnicalWrite, t as BUILTIN_CALL_RESOLVERS } from "../../../resolvers-DlKJOZnk.js";
+import { i as resolveCall, n as ignoreCalls, r as isTechnicalWrite, t as BUILTIN_CALL_RESOLVERS } from "../../../resolvers-DhJO-qvQ.js";
 export { BUILTIN_CALL_RESOLVERS, ignoreCalls, isTechnicalWrite, resolveCall };

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

@@ -1,4 +1,24 @@
 import type { CallResolver } from './types.js';
+export declare const DISPATCH_METHODS: Set<string>;
+/**
+ * The method that actually runs the job, by queue package.
+ *
+ * There is no single name, and this list grew twice by measurement rather than by
+ * reasoning. `@rlanz/bull-queue` uses `handle`; `@nemoventures/adonis-jobs` calls
+ * it `process`; `@adonisjs/queue` — the official package — generates
+ * `async execute()` in its own `make:job` stub. Each omission cost the same: the
+ * file resolved, no body was found, the dispatch was reported as an unknown, and
+ * every write inside the job went uncounted.
+ *
+ * `execute` surfaced only once event dispatch started being followed, because the
+ * listener was what enqueued the job and that path had never been walked. Which is
+ * the argument for adding a name when a real application shows it: a list written
+ * from imagination would have missed this one too.
+ *
+ * Ordered: a class declaring more than one is answering the dispatcher with the
+ * first, and `handle` is the most common.
+ */
+export declare const EXECUTION_METHODS: readonly ["handle", "execute", "process", "run", "perform"];
 /**
  * "Job" pattern: the write happens asynchronously.
  *

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

@@ -0,0 +1,24 @@
+import type { CallExpression } from 'ts-morph';
+import type { CallResolver } from './types.js';
+/**
+ * "Local function" pattern: a helper declared in the same file, not imported.
+ *
+ *     const lista = await proximos(id)          // function proximos() { … }
+ *     return rows.map(paraLinha)                // const paraLinha = (row) => …
+ *
+ * A query object that keeps its helpers beside it is common, and before this
+ * every such call was unresolved: the store a helper read was reached by nobody
+ * from that route, and a value built by it left as a whole table handed in.
+ *
+ * Only module-level declarations: a closure declared inside a body is part of
+ * that body, and the graph already walks it.
+ */
+export declare const localFunctionResolver: CallResolver;
+/**
+ * The function a call names: `proximos(id)` names `proximos`; `rows.map(paraLinha)`
+ * names `paraLinha`, called once per row — the body the graph must read is the
+ * same, whichever way it was reached.
+ */
+export declare function calledFunctionOf(call: CallExpression): import('ts-morph').Identifier | null;
+/** `function name() {}` or `const name = () => {}` / `function () {}` at module level */
+export declare function declaresFunction(file: import('ts-morph').SourceFile, name: string): boolean;

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

@@ -1,25 +1,2 @@
 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/sources/commands.d.ts

@@ -0,0 +1,14 @@
+import type { ClassDeclaration } from 'ts-morph';
+import type { AppContext } from '../app_context.js';
+import type { CollectedEntryPoint } from './routes_ast.js';
+export declare const GENERATES_DATA_HINT = "imports @faker-js/faker: generates data, probably a development tool";
+export declare function collectCommands(app: AppContext): CollectedEntryPoint[];
+/**
+ * The input DETs of a command: its `@flags.*` and `@args.*`, named as the
+ * operator types them — `flagName` / `argumentName` when given, the property
+ * otherwise. Returned as `flags.<name>` / `args.<name>` so the counter can say
+ * which is which.
+ */
+export declare function commandFieldsOf(cls: ClassDeclaration): string[];
+/** is this class an ace command? — the graph asks, to read its flags as input */
+export declare function isCommandClass(cls: ClassDeclaration): boolean;

package/build/src/inventory/sources/jobs.d.ts

@@ -0,0 +1,27 @@
+import type { AppContext } from '../app_context.js';
+/**
+ * The application's queue jobs, and who dispatches each — plan 0.7 §D.
+ *
+ * A job dispatched by a handler is part of that handler's transaction (§9): the
+ * user clicks, the effect happens, asynchronously or not. A job that NO
+ * transaction reaches is one of two things, and the code cannot say which:
+ *
+ *   scheduled    `PodarAuditoriaJob.schedule({}).cron('0 3 * * *')` in a start
+ *                file — an elementary process nobody is counting
+ *   dead code    dispatched by nothing at all
+ *
+ * Reported, not counted: inventing an elementary process is the error this
+ * package exists to avoid. When a scheduler appears on a real application, it
+ * becomes an entry point `job:<Class>` with the identity §5 already decided.
+ */
+export type CollectedJob = {
+    /** the class name */
+    name: string;
+    /** absolute, posix */
+    file: string;
+    /** files that dispatch it (`X.dispatch(…)`), absolute posix — inside a transaction or not */
+    dispatchedFrom: string[];
+    /** files that schedule it (`X.schedule({}).cron(…)`): a scheduler, which no transaction is */
+    scheduledFrom: string[];
+};
+export declare function collectJobs(app: AppContext): CollectedJob[];

package/build/src/pipeline.js

@@ -1,2 +1,2 @@
-import { n as analyze, t as CoverageTooLowError } from "../pipeline-Cq4dNTNE.js";
+import { n as analyze, t as CoverageTooLowError } from "../pipeline-C6kHKB9-.js";
 export { CoverageTooLowError, analyze };

package/build/src/types.d.ts

@@ -74,6 +74,12 @@ export type EntryPoint = {
     /** route name when present; not the identity used across versions */
     name?: string;
     handler: HandlerRef | null;
+    /**
+     * What the collector noticed and the counter cannot decide: an ace command that
+     * imports a data generator is probably a development tool. Printed beside the
+     * function, so a person excludes it with `boundary.ignoreEntryPoints`.
+     */
+    hints?: string[];
     provenance: Provenance;
 };
 export type HandlerRef = {
@@ -114,6 +120,12 @@ export type HandlerBehavior = {
      * user-recognisable field crossing the boundary, which is §7.2's definition.
      */
     requestFields: Field[];
+    /**
+     * The `@flags.*` / `@args.*` an ace command declares — its input DETs, exact.
+     * Named `flags.<name>` / `args.<name>`, as the operator types them. Absent on
+     * an HTTP transaction.
+     */
+    commandFields?: Field[];
     /** the transaction reads the request in a way that enumerates nothing */
     opaqueRequest: boolean;
     /**
@@ -125,6 +137,17 @@ export type HandlerBehavior = {
     opaqueOutputFields: Field[];
     /** stores a transformer on the path is for: their keys leave, not their columns */
     transformedStores: string[];
+    /** what the transaction delivers: derived fields, raw stores, values nobody could read */
+    delivered: {
+        any: boolean;
+        fields: string[];
+        opaqueFields: string[];
+        stores: string[];
+    };
+    /** of the stores delivered raw to a page, the columns the page reads off them (§6, plan 0.8 §D) */
+    pageReads?: Record<string, string[]>;
+    /** stores a page could not be read for, and why: they leave whole */
+    unreadablePages?: Record<string, string>;
     /**
      * How each store was read: rows whole, `.select()` columns, or one aggregate
      * scalar; by its own chain (`direct`) or preloaded through another store (`via`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@filipebraida/adonis-function-points",
   "description": "Automated function point counting and code metrics for AdonisJS applications.",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "engines": {
     "node": ">=24.0.0"
   },