@filipebraida/adonis-function-points 0.1.0 → 0.3.0

package/build/src/cli.js

@@ -1,5 +1,5 @@
-import { t as CoverageTooLowError } from "../pipeline-BzP-ITGN.js";
-import { a as runInventory, i as runExplain, n as runCount, o as ConfigLoadError, r as runDiff, s as printResult, t as runCalibrate } from "../runners-Bt8tbISi.js";
+import { t as CoverageTooLowError } from "../pipeline-CIAydCcT.js";
+import { a as runInventory, c as ConfigLoadError, i as runExplain, n as runCount, o as runMetrics, r as runDiff, s as printResult, t as runCalibrate } from "../runners-CmxNHuuq.js";
 import path from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -23,6 +23,7 @@ Usage
 Commands
   count                    count the unadjusted function points
   inventory                the raw facts: stores, routes, tracing coverage
+  metrics                  density, coupling and conformance, from the same run
   explain <name>           why one function was counted that way
   diff <a.json> [b.json]   additions / modifications / deletions, and billable FP
                            one file compares against the current tree; two
@@ -105,6 +106,7 @@ async function run(argv, printer = CONSOLE) {
 	if (![
 		"count",
 		"inventory",
+		"metrics",
 		"explain",
 		"diff",
 		"calibrate"
@@ -153,6 +155,13 @@ async function run(argv, printer = CONSOLE) {
 				out: text(flags.get("out"))
 			});
 			break;
+		case "metrics":
+			result = await runMetrics({
+				root,
+				out: text(flags.get("out")),
+				json: flags.get("json") === true
+			});
+			break;
 		case "explain":
 			result = await runExplain({
 				root,

package/build/src/define_config.d.ts

@@ -1,4 +1,5 @@
 import type { ComplexityTable } from './albrecht/tables.js';
+import type { ChangeFactors, ChangeReasonFactors } from './albrecht/diff.js';
 import type { CallResolver } from './inventory/resolvers/types.js';
 import type { Complexity, FunctionType } from './types.js';
 /**
@@ -35,6 +36,20 @@ export type FunctionPointsConfig = {
          * For example, tables mirrored from an external ERP.
          */
         externallyMaintained?: string[];
+        /**
+         * Stores the AFP naming filter excluded, which are business data here.
+         *
+         * The filter (§6.5.2.1.1, patterns in §6.5.2.1.3) catches names containing
+         * `session`, `template`, `error`, `types` and so on, because in most
+         * applications those hold infrastructure. When they hold the business —
+         * a chat session the user manages, a document template they maintain — the
+         * exclusion is wrong and no heuristic can know it. This wins over the
+         * filter, and the report says which stores were brought back.
+         *
+         * It is the counterpart of `infrastructure`: that one excludes what the
+         * filter missed, this one restores what it caught by accident.
+         */
+        business?: string[];
         /**
          * Entry points with no functional value to the user, by route name or by
          * identity (`GET /health`).
@@ -72,6 +87,25 @@ export type FunctionPointsConfig = {
     complexityTables?: Partial<Record<FunctionType, ComplexityTable>>;
     /** Weights per type and complexity. */
     weights?: Partial<Record<FunctionType, Record<Complexity, number>>>;
+    /**
+     * How change is priced, for `fp:diff`. A clause of the contract, not a flag.
+     *
+     * The AEP anchors are explicit for added (1) and deleted (0.4). For a modified
+     * function AEP grades the factor from 0.25 to 1.75 through Effort Complexity
+     * variation, which needs cyclomatic complexity this package does not measure —
+     * so it defaults to 1, which overestimates, and every diff says so.
+     *
+     * `reasonFactors` is the lever the default leaves on the table. The tool
+     * already distinguishes a change of type, a change of size, and a change of
+     * implementation only — same type, same DET, same FTR, different body — and on
+     * a real pair of releases the last was 151 of 378 FP billed as change. Pricing
+     * a refactor at full functional value is not defensible; pricing it at a number
+     * this package invented would be worse. So the number comes from the contract.
+     */
+    diff?: {
+        factors?: Partial<ChangeFactors>;
+        reasonFactors?: ChangeReasonFactors;
+    };
     /**
      * Custom tracing strategies, added to the built-in ones and running
      * **before** them.
@@ -93,7 +127,7 @@ export type FunctionPointsConfig = {
     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 name it has in the count (`Invoice`, `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,

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

@@ -31,6 +31,14 @@ export type PersistenceAccess = {
      * relation out of the count (§6.5.4) when it is a legitimate EIF.
      */
     viaRelation?: string;
+    /**
+     * Whether the access WRITES the related table.
+     *
+     * `preload('author')` reads it; `related('files').create(…)` writes it. Treating
+     * every relation access as a read made a table written only through a relation
+     * look externally maintained.
+     */
+    relationWritten?: boolean;
     /**
      * Does this access fire the model's hooks?
      *

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

@@ -1,6 +1,7 @@
 import type { ClassDeclaration, SourceFile } from 'ts-morph';
 import type { AppContext } from '../app_context.js';
 import type { CollectedDataStore } from '../sources/data_stores.js';
+import type { EventBindings } from '../sources/event_bindings.js';
 import type { CallResolver } from '../resolvers/types.js';
 import type { HandlerRef, TraceStep, UnresolvedCall } from '../../types.js';
 /**
@@ -34,6 +35,16 @@ export type Behavior = {
      * fields of the VineJS schema — counting-decisions §7.
      */
     inputFields: string[];
+    /** input fields that enumerate nothing: an open `vine.object` */
+    opaqueInputFields: string[];
+    /**
+     * Fields read straight off the request. Kept apart from `inputFields` so the
+     * conformance metric keeps meaning what it says: these are DETs, and they are
+     * not a validator.
+     */
+    requestFields: string[];
+    /** the transaction reads the request in a way that enumerates nothing */
+    opaqueRequest: boolean;
     trace: TraceStep[];
     /** bodies reached, for `fp:diff` */
     scope: ScopeEntry[];
@@ -49,6 +60,12 @@ export type GraphOptions = {
      * pattern, so a project with its own convention registers it here.
      */
     callResolvers?: CallResolver[];
+    /**
+     * Which listeners each event reaches. Collected by the caller, because the
+     * binding lives in a preload file and is an application-wide fact, like the
+     * data stores.
+     */
+    eventBindings?: EventBindings;
 };
 /**
  * Analyzer with state shared across handlers.
@@ -60,6 +77,7 @@ export type GraphOptions = {
  */
 export declare function createAnalyzer(app: AppContext, stores: CollectedDataStore[], options?: GraphOptions): {
     analyze: (handler: HandlerRef) => Behavior;
+    writtenAnywhere: () => Set<string>;
     /** how many files the project loaded — used to prove it does not grow */
     fileCount: () => number;
 };
@@ -78,3 +96,14 @@ export declare function analyzeHandler(app: AppContext, stores: CollectedDataSto
  * as any import. No type checker is needed.
  */
 export declare function injectedFor(owner: ClassDeclaration | undefined, file: SourceFile, app: AppContext): Map<string, string>;
+/**
+ * Both maps a file's imports produce: where a local name resolves, and what it
+ * was called where it was exported.
+ *
+ * Exported because the tests need the same answer the pipeline gets: a second
+ * implementation in the helpers drifted from this one and missed aliases.
+ */
+export declare function importMapsOf(file: SourceFile, app: AppContext): {
+    imports: Map<string, string>;
+    exportedAs: Map<string, string>;
+};

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

@@ -1,6 +1,19 @@
 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;
+/**
+ * Iteration over a list, checked BEFORE the resolvers run.
+ *
+ * `PAPEIS_CONCEDIVEIS.map((name) => …)` is `Identifier.method(args)`, the shape
+ * `static-service` exists for, so the resolver claimed it, resolved the enum
+ * module, found no `map` in it and reported a gap — noise never got asked,
+ * because it is only consulted once every resolver has declined.
+ *
+ * No resolver's pattern is `X.map(callback)`, so refusing this shape up front
+ * costs nothing and is not the same as silencing an unresolved call: nothing
+ * was ever there to resolve.
+ */
+export declare function isIterationCall(call: CallExpression): 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

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

@@ -0,0 +1,17 @@
+import type { CallResolver } from './types.js';
+/**
+ * "Event" pattern: the handler announces, and listeners act.
+ *
+ *     await events.OrderPlaced.dispatch(order.id)
+ *
+ * Runs BEFORE `job-dispatch`, which matches `Identifier.dispatch(args)` — the
+ * shape the direct form takes. Left to it, the event class was resolved and
+ * searched for a `handle` it does not declare (`dispatch` comes from
+ * `BaseEvent`), so the call was reported as an unknown and the listeners' reads
+ * and writes went uncounted.
+ *
+ * COUNTING DECISION: the same one taken for a job. The user clicks, the effect
+ * happens, and AFP §6.5.3 requires aggregating every path the transaction
+ * reaches — the emitter is an implementation detail of how it gets there.
+ */
+export declare const eventDispatchResolver: CallResolver;

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

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

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

@@ -1,5 +1,6 @@
 import type { CallExpression, SourceFile } from 'ts-morph';
 import type { DataStore, HandlerRef } from '../../types.js';
+import type { EventBindings } from '../sources/event_bindings.js';
 /**
  * AdonisJS does not impose a code organisation. The same transaction can be
  * written in very different ways:
@@ -26,6 +27,16 @@ export type ResolverContext = {
     depth: number;
     /** file imports: local identifier -> resolved absolute path */
     imports: Map<string, string>;
+    /**
+     * Local identifier -> the name it was exported under, when they differ.
+     *
+     * `import { createUser as create }` binds `create` locally while the function
+     * is `createUser` in its own file. Following the local name looks for a body
+     * that does not exist, and the call is reported as unresolved for a reason
+     * that is not true. Identity is the (specifier, exported name) pair — the same
+     * mistake the data-store collector had to unlearn.
+     */
+    exportedAs: Map<string, string>;
     /**
      * Injected dependencies visible in this body: property name -> class file.
      * For example `billing` -> `.../billing_service.ts`.
@@ -45,6 +56,15 @@ export type ResolverContext = {
      * it were business code.
      */
     dataStoresBySymbol: Map<string, DataStore>;
+    /**
+     * Which listeners each event reaches, read from `emitter.on(...)`.
+     *
+     * Empty when the application declares no bindings. Like the data stores, this
+     * is collected BEFORE any handler analysis: a dispatch cannot be followed
+     * from the call site alone, because the binding lives in a preload file the
+     * handler never imports.
+     */
+    eventBindings: EventBindings;
     /** resolves an AdonisJS specifier (`#collect/models/invite`) to a path */
     resolveSpecifier(specifier: string): string | null;
     /** loads a file into the project, if it exists */
@@ -62,4 +82,19 @@ export interface CallResolver {
     /** lower runs first; specific strategies before generic ones */
     readonly order?: number;
     resolve(call: CallExpression, ctx: ResolverContext): HandlerRef[];
+    /**
+     * "This call is mine, and it reaches no data store."
+     *
+     * `resolve` has two outcomes where three are needed. Returning `[]` means
+     * *not recognised*, so a strategy that recognises a call perfectly well and
+     * knows it touches nothing countable had no way to say so: the call still
+     * landed in `unresolved`, and a project could not answer its own false
+     * positives without making the tool claim a body that does not exist.
+     *
+     * Declaring it here is deliberately louder than a name on a silence list.
+     * It costs a named strategy and a reason in the project's own config, and
+     * `fp:count` still reports the volume — because a silent drop is the worst
+     * defect this package can have, whoever writes it.
+     */
+    ignores?(call: CallExpression, ctx: ResolverContext): boolean;
 }

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

@@ -0,0 +1,44 @@
+import { Node } from 'ts-morph';
+import type { Expression, SourceFile } from 'ts-morph';
+import type { AppContext } from '../app_context.js';
+import type { HandlerRef } from '../../types.js';
+/**
+ * Which listeners each event reaches.
+ *
+ * `events.OrderPlaced.dispatch(id)` in a handler is the user's click, and the
+ * write happens in a listener. AFP §6.5.3 requires aggregating every path a
+ * transaction reaches, so this is the same decision already taken for a job
+ * dispatch: the effect belongs to the transaction that caused it, whatever
+ * thread runs it.
+ *
+ * Without the binding the dispatch resolved to the event class, which declares
+ * no `dispatch` of its own — it inherits `BaseEvent` — so the call was reported
+ * as an unknown AND every read and write inside the listener went uncounted.
+ * That is the worst pairing: the gap is visible and the number is short.
+ *
+ * The binding is declared, not conventional: `emitter.on(event, [listeners])`
+ * in a preload file. It is therefore READ, never inferred from a name — the
+ * same rule the subpath imports follow.
+ */
+/** event class file (POSIX) -> the listener bodies it reaches */
+export type EventBindings = Map<string, HandlerRef[]>;
+/**
+ * All these functions need of the application: how to resolve a specifier.
+ *
+ * Narrowed on purpose, so the resolver can ask the same question of a call site
+ * without being handed the whole context — and so this file cannot start
+ * depending on more of it by accident.
+ */
+type SpecifierResolver = Pick<AppContext, 'resolveSpecifier'>;
+export declare function collectEventBindings(app: AppContext): EventBindings;
+/**
+ * The event class a dispatch or a binding names.
+ *
+ * Two shapes reach here: the class imported directly, and the generated
+ * registry (`events.OrderPlaced`), which is what `node ace make:event` produces
+ * and therefore the common one. Exported because the resolver has to ask the
+ * same question of a call site, and two implementations of "which event is
+ * this" would drift.
+ */
+export declare function resolveEventClass(expression: Expression | Node, from: SourceFile, app: SpecifierResolver): string | null;
+export {};

package/build/src/metrics/structure.d.ts

@@ -50,8 +50,22 @@ export declare function measureStructure(inventory: Inventory, count: CountResul
  * is what turns into a standards audit.
  */
 export type Conformance = {
-    /** write transactions whose input fields come from a validator */
-    writesWithValidator: {
+    /**
+     * Of the transactions that TAKE input, how many declare it with a validator.
+     *
+     * The first version of this measured validators over all writes, and read
+     * 39% on a healthy application — which invited the conclusion that 61% of its
+     * writes were unvalidated. They were not: most were workflow triggers
+     * (`POST /orders/:id/submit`, `POST /orders/:id/clear`) that carry nothing
+     * beyond the route parameter, exactly as counting-decisions §7 describes. A
+     * metric that makes a reader draw a false conclusion is worse than no metric,
+     * and this one made its own author draw it.
+     *
+     * The denominator is therefore the transactions that read something: a
+     * validator, a `request.input(…)`, or an `all()`/`body()` the analysis cannot
+     * enumerate.
+     */
+    inputsWithValidator: {
         ok: number;
         total: number;
         ratio: number;

package/build/src/pipeline.js

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

package/build/src/reporters/table.d.ts

@@ -1,6 +1,16 @@
-import type { CountResult, CountedFunction } from '../types.js';
+import type { CountResult, CountedFunction, Inventory } from '../types.js';
 import type { FunctionPointDiff } from '../albrecht/diff.js';
+import type { Conformance, StructureMetrics } from '../metrics/structure.js';
 export declare function renderCount(result: CountResult): string;
 /** `fp:explain`: a function's provenance, which is what supports a dispute */
+/**
+ * Structure and conformance, beside the count and never instead of it.
+ *
+ * If function points pay, the team optimises function points — more models, more
+ * endpoints, less reuse. Density and coupling on the same report are the
+ * counterweight, which is why this shares the inventory rather than collecting
+ * anything of its own.
+ */
+export declare function renderMetrics(structure: StructureMetrics, conformance: Conformance, coverage: Inventory['coverage']): string;
 export declare function renderExplain(fn: CountedFunction): string;
 export declare function renderDiff(diff: FunctionPointDiff): string;

package/build/src/types.d.ts

@@ -86,6 +86,23 @@ export type HandlerBehavior = {
     touches: string[];
     /** declared input fields (validators) */
     inputFields: Field[];
+    /**
+     * Input fields that enumerate nothing — an open `vine.object`.
+     *
+     * They count 1 DET each, like an opaque column, and are reported: the number
+     * is a floor, not a measurement.
+     */
+    opaqueInputFields: Field[];
+    /**
+     * Input fields read straight off the request, with no validator.
+     *
+     * Kept apart from `inputFields` so the conformance metric keeps meaning what it
+     * says. They are DETs all the same: `request.input('title')` is a
+     * user-recognisable field crossing the boundary, which is §7.2's definition.
+     */
+    requestFields: Field[];
+    /** the transaction reads the request in a way that enumerates nothing */
+    opaqueRequest: boolean;
     /** declared output fields (transformers, DTOs) */
     outputFields: Field[];
     /** path walked through the call graph — what `fp:explain` prints */

package/build/stubs/config.stub

@@ -12,6 +12,16 @@ export default defineConfig({
     infrastructure: ['access_tokens', 'reset_password_tokens', 'audits'],
     ignoreEntryPoints: ['drive.fs.serve', 'prometheus.metrics'],
     externallyMaintained: [],
+
+    /**
+     * Business data the AFP naming filter excluded by accident.
+     *
+     * It drops anything containing `session`, `template`, `error` or `types`,
+     * which is right for infrastructure and wrong for, say, a chat session the
+     * user manages. Check the confidence block of `fp:count` for what it
+     * excluded, and list here what is really business.
+     */
+    business: [],
   },
 
   /** Logical subgroups (RET). `constant` pins it at 1, which is honest. */
@@ -32,6 +42,22 @@ export default defineConfig({
    * here.
    */
   // overrides: {
-  //   'POST /petitions': { det: 42, reason: 'JSON Schema form; 42 user fields' },
+  //   'POST /forms': { det: 42, reason: 'JSON Schema form; 42 user fields' },
+  // },
+
+  /**
+   * How change is priced. A clause of the contract, not a flag.
+   *
+   * AEP anchors added at 1 and deleted at 0.4. For a MODIFIED function it grades
+   * the factor from 0.25 to 1.75 through Effort Complexity variation, which needs
+   * cyclomatic complexity this package does not measure — so it defaults to 1,
+   * which overestimates, and every `fp:diff` says so.
+   *
+   * `implementation` means same type, same DET, same FTR, different body: a
+   * refactor. Whether that is billable, and at what, is a decision for whoever
+   * signs the contract — not one this package should invent.
+   */
+  // diff: {
+  //   reasonFactors: { implementation: 0.25 },
   // },
 })

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.1.0",
+  "version": "0.3.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -9,6 +9,7 @@
   "files": [
     "build",
     "bin/cli.js",
+    "CHANGELOG.md",
     "!build/bin",
     "!build/tests"
   ],

package/build/define_config-DOqWyPwV.js

@@ -1,19 +0,0 @@
-//#region src/define_config.ts
-const DEFAULTS = {
-	boundary: {},
-	retStrategy: "constant",
-	maxDepth: 3,
-	messageDet: 0
-};
-function defineConfig(config) {
-	return {
-		...DEFAULTS,
-		...config,
-		boundary: {
-			...DEFAULTS.boundary,
-			...config.boundary
-		}
-	};
-}
-//#endregion
-export { defineConfig as n, DEFAULTS as t };

package/build/scripts/smoke_package.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_cli.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_cmp.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_count.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_data.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_diff.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_gap.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_graph.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_metrics.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_miss.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_names.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_nodata.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_one.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_perf.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_routes.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_unres.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tmp/probe_vazquez.d.ts

@@ -1 +0,0 @@
-export {};

package/build/tsdown.config.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("tsdown").UserConfig;
-export default _default;