@filipebraida/adonis-function-points 0.3.0 → 0.5.0

package/build/{resolvers-CRB6lXoo.js → resolvers-PJwo2Z8R.js}

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { Node, Project, SyntaxKind } from "ts-morph";
 //#region src/inventory/paths.ts
 /**
@@ -20,8 +21,61 @@ import { Node, Project, SyntaxKind } from "ts-morph";
 * it to each comparison costs vigilance forever.
 */
 const toPosix = (value) => value.split("\\").join("/");
+/**
+* A path as it should appear in an EMITTED artefact: relative to the application.
+*
+* `CountSource.app` is documented as never being the absolute path, because that
+* says where the machine keeps its files and travels with every count sent
+* anywhere. One field below it, `config` shipped the absolute path — and so did
+* every `trace[].file`, 858 times in a single production count. The rule was
+* stated and then applied to one field.
+*
+* Internally the absolute path is the right thing: it is what ts-morph resolves
+* and what the call graph keys its caches on. So this converts at the boundary
+* where a path LEAVES, and nowhere else.
+*
+* A path outside the root keeps its `../` prefix, which describes where it is
+* without naming the home directory.
+*/
+const relativeTo = (root, value) => toPosix(path.relative(toPosix(root), toPosix(value))) || ".";
 /** Compares two paths that may have come from different sources. */
 const samePath = (a, b) => a !== void 0 && b !== void 0 && toPosix(a) === toPosix(b);
+/**
+* Is this file the application's own code, as opposed to the scaffolding around it?
+*
+* The top-level filter on `scanRoots` already drops `tests/`, `database/` and the
+* rest — but only at the ROOT. Applications organised by domain module put both
+* inside `app/`:
+*
+*     app/billing/tests/functional/invoice.spec.ts
+*     app/billing/seeders/plan_seeder.ts
+*
+* so they land in the project, and `writtenAnywhere()` read a seeder's inserts as
+* the application maintaining the table. A reference table only the seed populates
+* came out as an ILF — which the CPM does not allow: data maintained by the
+* development team is at most an EIF, and code data is not counted at all.
+*
+* The segments are AdonisJS's own: `make:test` writes to a suite directory,
+* `make:seeder` to `seeders`, `make:migration` to `migrations`, `make:factory` to
+* `factories`. The `.spec`/`.test` suffixes come from the suite globs in
+* `adonisrc.ts`.
+*/
+const SCAFFOLDING = new Set([
+	"tests",
+	"test",
+	"seeders",
+	"seeder",
+	"migrations",
+	"factories"
+]);
+function isApplicationCode(root, file) {
+	const relative = relativeTo(root, file);
+	if (relative.startsWith("..")) return false;
+	const parts = relative.split("/");
+	const name = parts.at(-1) ?? "";
+	if (/\.(spec|test)\.[jt]s$/.test(name)) return false;
+	return !parts.slice(0, -1).some((segment) => SCAFFOLDING.has(segment));
+}
 //#endregion
 //#region src/inventory/sources/event_bindings.ts
 /** the method a listener declares; AdonisJS calls `handle` unless told otherwise */
@@ -799,6 +853,15 @@ const BUILTIN_CALL_RESOLVERS = [
 * them apart. Hence specific strategies declare a lower `order` than generic
 * ones, and `module-function` comes last — it would match almost anything.
 */
+/**
+* Does any strategy call this a technical write?
+*
+* Asked separately from resolution, because the strategy that recognises the call as
+* incidental is not necessarily the one that knows where it goes.
+*/
+function isTechnicalWrite(call, ctx, resolvers = BUILTIN_CALL_RESOLVERS) {
+	return resolvers.some((resolver) => resolver.technicalWrite?.(call, ctx) === true);
+}
 function resolveCall(call, ctx, resolvers = BUILTIN_CALL_RESOLVERS) {
 	for (const resolver of resolvers) {
 		/**
@@ -819,4 +882,4 @@ function resolveCall(call, ctx, resolvers = BUILTIN_CALL_RESOLVERS) {
 	return null;
 }
 //#endregion
-export { rootSymbolOf as a, toPosix as c, hooksFiredBy as i, resolveCall as n, collectEventBindings as o, detectAccess as r, samePath as s, BUILTIN_CALL_RESOLVERS as t };
+export { hooksFiredBy as a, isApplicationCode as c, toPosix as d, detectAccess as i, relativeTo as l, isTechnicalWrite as n, rootSymbolOf as o, resolveCall as r, collectEventBindings as s, BUILTIN_CALL_RESOLVERS as t, samePath as u };

package/build/{runners-CmxNHuuq.js → runners-DIt1G85i.js}

@@ -1,6 +1,6 @@
 import { c as diffCounts, i as measureStructure, l as DEFAULTS, n as parseSamples, o as IncomparableRulesetsError, r as measureConformance, s as IncomparableSourcesError, t as calibrate, u as defineConfig } from "./calibration-8eV8CEix.js";
-import { c as toPosix } from "./resolvers-CRB6lXoo.js";
-import { n as analyze } from "./pipeline-CIAydCcT.js";
+import { d as toPosix } from "./resolvers-PJwo2Z8R.js";
+import { n as analyze } from "./pipeline-CNTBhs6o.js";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { existsSync } from "node:fs";
@@ -91,7 +91,12 @@ function renderCount(result) {
 	* habit: if it grows, the count comes from a spreadsheet and the tool loses
 	* its reason to exist. Printing the share is what keeps that visible.
 	*/
-	const overridden = result.functions.filter((fn) => fn.rationale.overrides?.length);
+	/**
+	* Only entries that DECLARED a number. A review records a decision and declares
+	* nothing, so counting it here would read as "35% of the total declared by
+	* override" about a count nobody touched.
+	*/
+	const overridden = result.functions.filter((fn) => fn.rationale.overrides?.some((o) => o.fields.length > 0));
 	if (overridden.length > 0) {
 		const points = overridden.reduce((total, fn) => total + fn.points, 0);
 		const share = (points / (result.totals.unadjusted || 1) * 100).toFixed(1);
@@ -359,7 +364,17 @@ async function runMetrics(options) {
 async function runExplain(options) {
 	const { config, notes } = await configFor(options.root);
 	const { count } = await analyze(options.root, config);
-	const matched = count.functions.filter((fn) => fn.name.toLowerCase().includes(options.name.toLowerCase()));
+	/**
+	* An exact name wins outright; the substring search is the fallback.
+	*
+	* `fp:explain "POST /orders/:param/submit"` returned four functions, because
+	* `/submit`, `/submit-ready` and `/submit-ready/return` all contain it. Asking
+	* about a function by its exact name and being handed its neighbours makes the
+	* command useless for the thing it exists for — defending one number.
+	*/
+	const wanted = options.name.toLowerCase();
+	const exact = count.functions.filter((fn) => fn.name.toLowerCase() === wanted);
+	const matched = exact.length > 0 ? exact : count.functions.filter((fn) => fn.name.toLowerCase().includes(wanted));
 	if (matched.length === 0) return {
 		output: "",
 		notes,

package/build/src/albrecht/counter.d.ts

@@ -34,7 +34,7 @@ export declare const RULESET = "afp";
  * against this one and bills the tool's own improvement as work done. The guard
  * exists for exactly that, and only this constant arms it.
  */
-export declare const RULESET_VERSION = "1.2.0";
+export declare const RULESET_VERSION = "1.4.0";
 export type CountInput = {
     app: AppContext;
     stores: CollectedDataStore[];

package/build/src/albrecht/transactional_functions.d.ts

@@ -31,5 +31,14 @@ export type TransactionOptions = {
     messageDet: number;
     tables: Record<FunctionType, ComplexityTable>;
     weights: Record<FunctionType, Record<Complexity, number>>;
+    /**
+     * Application root, used only to relativise the paths that LEAVE in the trace.
+     *
+     * `CountSource.app` is documented as never being the absolute path, because it
+     * says where the machine keeps its files and travels with every count sent
+     * anywhere. The trace shipped the absolute path regardless — 858 times in a
+     * single production count, which is most of the artefact a ledger would store.
+     */
+    root: string;
 };
 export declare function countTransactionalFunctions(entryPoints: CollectedEntryPoint[], behaviors: Map<string, Behavior>, options: TransactionOptions): CountedFunction[];

package/build/src/cli.js

@@ -1,5 +1,5 @@
-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 { t as CoverageTooLowError } from "../pipeline-CNTBhs6o.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-DIt1G85i.js";
 import path from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";

package/build/src/define_config.d.ts

@@ -161,9 +161,34 @@ export type FunctionOverride = {
      *
      * A name that matches no schema is a warning, never a silent fallback.
      */
-    detFromSchema?: string;
+    /**
+     * Name of a declared schema, or several whose fields are UNIONED.
+     *
+     * An ILF's DETs are the fields the user recognises in the file, and an
+     * application with one schema per template recognises the fields of all of them.
+     * Pointing at the largest and justifying it in `reason` gives the same answer
+     * only while they land in the same complexity band — which is a piece of
+     * reasoning the configuration should not have to carry.
+     *
+     * Unioned by leaf path, so a field two templates share counts once.
+     */
+    detFromSchema?: string | string[];
     /** declared RET (data function) or FTR (transaction) */
     refs?: number;
+    /**
+     * Opaque DETs someone has looked at and decided are correct at 1.
+     *
+     * `fp:count` reports every opaque column and open input object, because 1 DET is
+     * a floor rather than a measurement. But some of them ARE one field — a copy, a
+     * checksum, a bag of metadata — and there was no way to say so, so the warning
+     * fired on every run forever. A warning that cannot be answered is a warning the
+     * team learns to scroll past, which costs more than the one it reports.
+     *
+     * It silences nothing else: the count does not move, and `fp:count` still says
+     * how many were reviewed. Names are matched bare (`schema`) or qualified
+     * (`Petition.schema`).
+     */
+    opaqueReviewed?: string[];
     /** why — required, and printed by `fp:explain` beside the number */
     reason: string;
 };

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

@@ -30,6 +30,16 @@ export type Behavior = {
     writes: boolean;
     /** data stores reached */
     touches: string[];
+    /**
+     * Of those, the ones this transaction WRITES.
+     *
+     * `writes` is a property of the transaction — it decides EI against EO — and was
+     * being read as a property of every store the transaction touched: a table merely
+     * read by a route that writes something else counted as maintained, so almost
+     * nothing could be an EIF. §6.5.4 asks who maintains THIS store, which is a
+     * question about the access, not about the request.
+     */
+    writtenStores: string[];
     /**
      * Declared input fields: `request.validateUsing(x)` resolved down to the
      * fields of the VineJS schema — counting-decisions §7.

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

@@ -18,5 +18,23 @@
  * it to each comparison costs vigilance forever.
  */
 export declare const toPosix: (value: string) => string;
+/**
+ * A path as it should appear in an EMITTED artefact: relative to the application.
+ *
+ * `CountSource.app` is documented as never being the absolute path, because that
+ * says where the machine keeps its files and travels with every count sent
+ * anywhere. One field below it, `config` shipped the absolute path — and so did
+ * every `trace[].file`, 858 times in a single production count. The rule was
+ * stated and then applied to one field.
+ *
+ * Internally the absolute path is the right thing: it is what ts-morph resolves
+ * and what the call graph keys its caches on. So this converts at the boundary
+ * where a path LEAVES, and nowhere else.
+ *
+ * A path outside the root keeps its `../` prefix, which describes where it is
+ * without naming the home directory.
+ */
+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;
+export declare function isApplicationCode(root: string, file: string): boolean;

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

@@ -17,6 +17,13 @@ export declare const BUILTIN_CALL_RESOLVERS: CallResolver[];
  * them apart. Hence specific strategies declare a lower `order` than generic
  * ones, and `module-function` comes last — it would match almost anything.
  */
+/**
+ * Does any strategy call this a technical write?
+ *
+ * Asked separately from resolution, because the strategy that recognises the call as
+ * incidental is not necessarily the one that knows where it goes.
+ */
+export declare function isTechnicalWrite(call: import('ts-morph').CallExpression, ctx: import('./types.js').ResolverContext, resolvers?: CallResolver[]): boolean;
 export declare function resolveCall(call: import('ts-morph').CallExpression, ctx: import('./types.js').ResolverContext, resolvers?: CallResolver[]): {
     by: string;
     refs: import('../../types.js').HandlerRef[];

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

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

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

@@ -97,4 +97,23 @@ export interface CallResolver {
      * defect this package can have, whoever writes it.
      */
     ignores?(call: CallExpression, ctx: ResolverContext): boolean;
+    /**
+     * "This call writes, and the write is not what the transaction is FOR."
+     *
+     * AFP §6.5.3 decides EI against EO mechanically: a transaction that modifies a data
+     * store is an EI. That is deliberate — repeatability over CPM fidelity — and it
+     * misreads one shape: a screen that records a visit, a last-seen organisation, a
+     * view counter. The CPM asks what the elementary process is PRIMARILY for, and for a
+     * `GET` that shows a record while noting the visit, the answer is presentation.
+     *
+     * So the fact is declared about the CALL, not about each transaction that reaches it:
+     * `persistOrganizationVisit` is called from several screens and saying it once covers
+     * all of them.
+     *
+     * It does NOT hide the write. The store is still maintained by this application —
+     * still an ILF, still an FTR of the transaction — and only the transaction's
+     * classification changes. A resolver that wanted the write to disappear would use
+     * `ignores`, and would be wrong to.
+     */
+    technicalWrite?(call: CallExpression, ctx: ResolverContext): boolean;
 }

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

@@ -33,7 +33,14 @@ export type CountSource = {
      */
     dirty?: boolean;
     countedAt: string;
-    /** configuration file that shaped the count, or null for the defaults */
+    /**
+     * Configuration file that shaped the count, RELATIVE to the application root,
+     * or null for the defaults.
+     *
+     * Relative for the same reason `app` is a name: an absolute path says where the
+     * machine keeps its files, and this artefact is what goes into a ledger and to
+     * whoever receives the invoice.
+     */
     config: string | null;
 };
 export declare function describeSource(root: string, config: string | null): CountSource;

package/build/src/pipeline.js

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

package/build/src/types.d.ts

@@ -84,6 +84,8 @@ export type HandlerBehavior = {
     writes: boolean;
     /** DataStores reached (ids) */
     touches: string[];
+    /** of those, the ones this transaction writes — §6.5.4 is per store, not per request */
+    writtenStores: string[];
     /** declared input fields (validators) */
     inputFields: Field[];
     /**

package/build/stubs/config.stub

@@ -42,7 +42,13 @@ export default defineConfig({
    * here.
    */
   // overrides: {
-  //   'POST /forms': { det: 42, reason: 'JSON Schema form; 42 user fields' },
+  //   // one schema, or several whose fields are unioned by leaf path
+  //   Form: { detFromSchema: ['intakeSchema', 'reviewSchema'], reason: 'one per template' },
+  //
+  //   // 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' },
   // },
 
   /**

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