@filipebraida/adonis-function-points 0.5.0 → 0.7.0

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

@@ -0,0 +1,88 @@
+import { Node } from 'ts-morph';
+import type { CallExpression, SourceFile } from 'ts-morph';
+import type { RelationMap, StoreSymbols } from '../detectors/lucid.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 = 
+/** 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;

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

@@ -0,0 +1,143 @@
+import { Node } 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.
+ *
+ * AFP §7.3 counts one DET per unique field that leaves the boundary. Without
+ * reading what leaves, the only repeatable answer is "every column of every
+ * table read", and that is what the count did: a detail screen passing through
+ * three transformers came out at 67 DET. The transformer is where the
+ * application says which fields cross, so it is read here.
+ *
+ * Two facts are extracted, and both are about the BODY, so they are cached with
+ * the rest of its facts:
+ *
+ *   outputs   the keys a transformer method returns — `LivroTransformer.titulo`
+ *   selected  the columns a query names in `.select()` — per store
+ *
+ * Everything the walker cannot read is a placeholder, never a guess: an
+ * unreadable spread counts 1 DET as a floor and is reported, the same treatment
+ * an open `vine.object` gets on the input side (§9).
+ */
+export type OutputFacts = {
+    /** qualified keys emitted by this transformer body */
+    outputs: string[];
+    /** of those, the placeholders: a spread the walker could not read */
+    opaqueOutputs: string[];
+    /**
+     * The store this transformer is FOR — `BaseTransformer<Livro>` — when it is a
+     * known store. A transformer decides what leaves for its resource, not for the
+     * page: a store read beside it and passed raw is not covered.
+     */
+    resource: string | null;
+};
+/** how a body reads a store, per chain — what leaves when nothing transforms it */
+export type StoreRead = {
+    store: string;
+    shape: 'whole' | 'select' | 'aggregate';
+    /** for `select`: the columns named */
+    columns: string[];
+    /**
+     * The store this one was preloaded THROUGH (`Livro.query().preload('autor')`),
+     * when it was not read by a chain of its own. A relation loaded for a
+     * transformer is consumed by it, not shown.
+     */
+    via?: string;
+};
+/**
+ * Does this class extend a transformer base from a package?
+ *
+ * Decided 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. Shared with the `transformer` resolver: one definition of
+ * what a transformer is, or the resolver follows a body this walker refuses.
+ */
+export declare function isTransformerClass(cls: ClassDeclaration): boolean;
+/** `class X extends BaseTransformer<Livro>` -> 'Livro' */
+export declare function transformerResourceOf(cls: ClassDeclaration): string | null;
+/**
+ * The keys a transformer method returns.
+ *
+ * `followed` says whether a call inside the literal is a body the graph walks —
+ * `AutorTransformer.transform(x)`, `this.toObject()` — in which case its keys
+ * arrive through that body and the key holding it is not a DET of its own: the
+ * user sees the author's name, not an "autor" field.
+ *
+ *   { titulo: l.titulo }                 1 — `titulo`
+ *   { autor: AutorTransformer.transform } 0 here; the nested 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
+ *
+ * A key that is the identifier of the transformer's resource is not a DET, for
+ * 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
+ * the same answer: `Livro.query().where(…).count()` is an aggregate whether the
+ * detector is looking at `query` or at `count`.
+ *
+ *   whole      rows leave: every column of the store (unless a transformer covers it)
+ *   select     only the columns named
+ *   aggregate  `.count()`, `.exists()`: one derived scalar leaves, not the table
+ */
+export type ChainShape = {
+    selected: string[];
+    aggregate: boolean;
+    /** a `.select()` whose column list is not literal */
+    unreadable: {
+        line: number;
+        expression: string;
+    }[];
+};
+export declare function chainShapeOf(access: CallExpression): ChainShape;
+export {};

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

@@ -37,4 +37,6 @@ export declare const toPosix: (value: string) => string;
 export declare const relativeTo: (root: string, value: string) => string;
 /** Compares two paths that may have come from different sources. */
 export declare const samePath: (a: string | undefined, b: string | undefined) => boolean;
+/** a seeder, by the directory `make:seeder` writes to — scaffolding, but a fact the report uses */
+export declare function isSeeder(root: string, file: string): boolean;
 export declare function isApplicationCode(root: string, file: string): boolean;

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

@@ -28,3 +28,24 @@ export declare function resolveCall(call: import('ts-morph').CallExpression, ctx
     by: string;
     refs: import('../../types.js').HandlerRef[];
 } | null;
+export type IgnoreCallsOptions = {
+    /** the strategy's name — printed in the report beside the volume it declared data-free */
+    name: string;
+    /** method names, matched on the callee: `getUrl` matches `x.getUrl(...)` */
+    methods?: string[];
+    /** a pattern over the callee's text: `/\bauthz\.can$/` */
+    matching?: RegExp;
+    /** lower runs first; defaults to 1, before every built-in */
+    order?: number;
+};
+/**
+ * A strategy that recognises a family of calls and knows they reach no data
+ * store — a rate limiter, an attachment's URL, an authorisation check.
+ *
+ * Read from a real configuration, every such strategy was the same eight lines:
+ * a helper to get the method name off the ts-morph node (the app does not depend
+ * on ts-morph), a `resolve` that returns nothing, and one comparison. What the
+ * design wants is kept — it is still a NAMED strategy, and `fp:count` still
+ * reports the volume it declared data-free — and the ceremony is not.
+ */
+export declare function ignoreCalls(options: IgnoreCallsOptions): CallResolver;

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

@@ -1,2 +1,2 @@
-import { n as isTechnicalWrite, r as resolveCall, t as BUILTIN_CALL_RESOLVERS } from "../../../resolvers-PJwo2Z8R.js";
-export { BUILTIN_CALL_RESOLVERS, isTechnicalWrite, resolveCall };
+import { i as resolveCall, n as ignoreCalls, r as isTechnicalWrite, t as BUILTIN_CALL_RESOLVERS } from "../../../resolvers-DaU4uAqT.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-CNTBhs6o.js";
+import { n as analyze, t as CoverageTooLowError } from "../pipeline-DO2301fV.js";
 export { CoverageTooLowError, analyze };

package/build/src/types.d.ts

@@ -45,6 +45,17 @@ export type Attribute = {
     name: string;
     type?: string;
     isIdentifier: boolean;
+    /**
+     * Maintained by the framework, not by the user: `autoCreate` / `autoUpdate`
+     * on a `@column.dateTime()`. Not a DET, on the same ground as the identifier —
+     * counting-decisions §6.
+     */
+    system?: boolean;
+    /**
+     * `serializeAs: null`: Lucid never serialises it, so it never leaves on an
+     * output. Still a DET of the data function — counting-decisions §6.
+     */
+    hidden?: boolean;
     provenance: Provenance;
 };
 /**
@@ -63,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 = {
@@ -103,10 +120,41 @@ 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;
-    /** declared output fields (transformers, DTOs) */
+    /**
+     * What a transformer on the path emits — counting-decisions §6. Empty means no
+     * transformer was reached and the output is counted from the stores' columns.
+     */
     outputFields: Field[];
+    /** output spreads the analysis could not read: 1 DET each, a floor */
+    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[];
+    };
+    /**
+     * How each store was read: rows whole, `.select()` columns, or one aggregate
+     * scalar; by its own chain (`direct`) or preloaded through another store (`via`).
+     */
+    outputReads: Record<string, {
+        whole: boolean;
+        selected: string[];
+        aggregate: boolean;
+        direct: boolean;
+        via: string[];
+    }>;
     /** path walked through the call graph — what `fp:explain` prints */
     trace: TraceStep[];
     /** calls no resolver knew how to follow */

package/build/stubs/config.stub

@@ -24,31 +24,44 @@ export default defineConfig({
     business: [],
   },
 
-  /** Logical subgroups (RET). `constant` pins it at 1, which is honest. */
-  retStrategy: 'constant',
+  /**
+   * How tables fold into data functions (RET). `usage`, the default: a
+   * `hasMany`/`hasOne` child no application code addresses directly is a RET of
+   * its parent, not an ILF of its own. `none` keeps every table apart, at RET 1,
+   * to compare against a count made before 0.6.0.
+   */
+  // dataFunctions: { grouping: 'usage' },
 
-  /** How far to follow the call graph from the handler. */
-  maxDepth: 3,
+  /** How far to follow the call graph from the handler (default 3). */
+  // maxDepth: 3,
 
   /** Refuses to emit a count if tracing covers less than this. */
   minCoverage: 0.85,
 
   /**
-   * Facts static analysis cannot read, declared with a required justification.
-   *
-   * The case this exists for: fields the user fills that live in a JSON column
-   * whose schema is stored in the database. See counting-decisions §8 — and use
-   * it sparingly, because `fp:count` reports what share of the total came from
-   * here.
+   * DETs static analysis cannot read — a JSON column, an open validator field —
+   * count 1 each, a floor, and `fp:count` names them. Answer them here by ORIGIN,
+   * with a required justification, and the answer reaches every function carrying
+   * the DET. See counting-decisions §8; use it sparingly, because `fp:count`
+   * reports what share of the total came from here.
    */
-  // overrides: {
-  //   // one schema, or several whose fields are unioned by leaf path
-  //   Form: { detFromSchema: ['intakeSchema', 'reviewSchema'], reason: 'one per template' },
+  // opaque: {
+  //   // the fields live in a JSON Schema declared in the code: name it (or several,
+  //   // unioned by leaf path), and the count keeps coming from the code
+  //   'Survey.answers': { schemas: ['surveySchema', 'feedbackSchema'], reason: 'one schema per survey template' },
+  //   'answerSurveyValidator.answers': { schemas: 'surveySchema', reason: 'the same form, submitted' },
   //
   //   // 1 DET is a floor, and `fp:count` says so on every run. When 1 IS the right
-  //   // answer, record that someone checked — otherwise the warning becomes noise
-  //   // the team learns to scroll past. It moves no number.
-  //   Petition: { opaqueReviewed: ['schema', 'uiSchema'], reason: 'metadata; one field each' },
+  //   // answer, record that someone checked — it moves no number
+  //   'Attachment.metadata': { reviewed: true, reason: 'size and mime type: one bag, one field' },
+  // },
+
+  /**
+   * A declared NUMBER for one function — the last resort, for a schema that lives
+   * only in the database. It freezes: prefer `opaque.<origin>.schemas`.
+   */
+  // overrides: {
+  //   'POST /surveys/:id/answers': { det: 42, reason: 'the form has 42 fields, defined in the database' },
   // },
 
   /**

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.5.0",
+  "version": "0.7.0",
   "engines": {
     "node": ">=24.0.0"
   },