@filipebraida/adonis-function-points 0.1.0

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

@@ -0,0 +1,39 @@
+/**
+ * What a count counted.
+ *
+ * A saved count used to say which RULESET produced it and nothing about its
+ * subject — no revision, no branch, no date. Two such files compare cleanly and
+ * mean nothing: the same application a month apart, or two different
+ * applications, are indistinguishable once the number is on an invoice.
+ *
+ * This is not hypothetical. A production application here moved from 714 to 768
+ * points, and the first explanation reached for was a defect in the counter.
+ * It was a month of development: the counter returned identical totals across
+ * twelve of its own commits. Half a day answering a question the artefact
+ * should have answered itself.
+ */
+export type CountSource = {
+    /**
+     * Identity of the application counted.
+     *
+     * The package.json name when there is one, the directory name otherwise —
+     * never the absolute path, which says where the machine keeps its files and
+     * travels with every count sent anywhere.
+     */
+    app: string;
+    /** commit counted, when the root is a git repository */
+    revision?: string;
+    branch?: string;
+    /**
+     * Uncommitted changes were present.
+     *
+     * The field that matters most in billing: a count taken over a dirty tree
+     * cannot be reproduced from any revision, and whoever receives the invoice is
+     * entitled to know that before paying it.
+     */
+    dirty?: boolean;
+    countedAt: string;
+    /** configuration file that shaped the count, or null for the defaults */
+    config: string | null;
+};
+export declare function describeSource(root: string, config: string | null): CountSource;

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

@@ -0,0 +1,31 @@
+import type { AppContext } from '../app_context.js';
+import type { DataStore, UnresolvedCall } from '../../types.js';
+/**
+ * Collects the logical data stores — ILF/EIF candidates.
+ *
+ * The failure this module exists to make impossible: an application can hold
+ * dozens of model files and ZERO `extends BaseModel` from Lucid, because the
+ * models extend schema classes generated from migrations. Reading only the
+ * model file would count zero for the whole application, **in silence**.
+ *
+ * The unit of work is therefore the INHERITANCE CHAIN, not the file:
+ *
+ *   class User extends BaseModel                        (direct)
+ *   class User extends UserSchema                       (generated schema)
+ *   class User extends compose(UserSchema, Auditable)   (mixin)
+ *
+ * Where the chain leaves the application — a mixin coming from a package —
+ * collection stops and **reports**. A soft-delete mixin adds `deletedAt`;
+ * pretending it does not exist would be counting wrong without warning.
+ */
+export type ColumnSource = 'ast' | 'generated-schema';
+export type CollectedDataStore = DataStore & {
+    /** where the columns came from; counts from different sources are not equivalent */
+    columnSource: ColumnSource;
+};
+export type DataStoreCollection = {
+    stores: CollectedDataStore[];
+    /** chains that left the application, required by AFP §6.5.3 */
+    unresolved: UnresolvedCall[];
+};
+export declare function collectDataStores(app: AppContext): Promise<DataStoreCollection>;

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

@@ -0,0 +1,32 @@
+import type { AppContext } from '../app_context.js';
+import type { Provenance } from '../../types.js';
+/**
+ * JSON Schema literals declared in the application's own code.
+ *
+ * Some applications store what the user fills as data — a form definition in a
+ * JSON column — which counting-decisions §8 says counts as 1 DET, because the
+ * schema is runtime data. That is true of the row in the database and false of
+ * the literal that seeded it: when the schema is an object literal in a seeder,
+ * it is code, and ts-morph reads it.
+ *
+ * This matters more than the number it yields. A hand-declared DET count
+ * freezes: someone adds a field, the count does not move, and `fp:diff` reports
+ * no change for real functional growth — undercounting silently and
+ * progressively, which is worse than undercounting once. Reading the schema
+ * keeps the number coming from the code, which is the property the whole package
+ * rests on.
+ *
+ * The leaf rules are §7's, unchanged — the same ones applied to VineJS
+ * validators. Only the recognition differs: `properties` and `items` instead of
+ * `vine.object` and `vine.array`.
+ */
+export type DiscoveredSchema = {
+    /** the declared name, which is what a config override refers to */
+    name: string;
+    /** user-recognisable fields, by the §7 leaf rules */
+    fields: number;
+    /** the leaf paths, so `fp:explain` can show where the number came from */
+    leaves: string[];
+    provenance: Provenance;
+};
+export declare function collectJsonSchemas(app: AppContext): Map<string, DiscoveredSchema>;

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

@@ -0,0 +1,28 @@
+import type { AppContext } from '../app_context.js';
+import type { EntryPoint, UnresolvedCall } from '../../types.js';
+/**
+ * Reads the HTTP entry points from the AST of the route files.
+ *
+ * On v7 the runtime is the primary source (`router.toJSON()` after boot), but
+ * this parser is what has to work first: fixtures do not boot, and the golden
+ * invariant depends on an application with no generated artefact at all.
+ *
+ * Traps, each one covered by a regression test:
+ *
+ *   router            multi-line route: the expression text contains the line
+ *     .post(...)      break, and without normalising it most routes never match
+ *
+ *   .resource(p, C)   expands to up to 7 routes, filtered by .only()/.apiOnly()
+ *   .group().prefix() the prefix must reach the final pattern, and accumulates
+ *   controllers.a.B   the bare name collides across modules: resolve by path
+ *   router.on(p)      entry point with no handler at all
+ */
+export type CollectedEntryPoint = EntryPoint & {
+    /** key that stays stable across versions — counting-decisions §5 */
+    identity: string;
+};
+export type EntryPointCollection = {
+    entryPoints: CollectedEntryPoint[];
+    unresolved: UnresolvedCall[];
+};
+export declare function collectEntryPoints(app: AppContext): Promise<EntryPointCollection>;

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

@@ -0,0 +1,72 @@
+import type { Inventory } from '../types.js';
+import type { CountResult } from '../types.js';
+/**
+ * Structural and density metrics, derived from the SAME inventory.
+ *
+ * Nothing here collects a new fact: once the graph knows which transactions
+ * reach which stores and which modules they pass through, coupling and density
+ * are arithmetic over that. It is also why the inventory layer knows nothing of
+ * FPA.
+ *
+ * Why they belong beside function points: if function points pay, the team
+ * optimises function points — more models, more endpoints, less reuse. Density
+ * and coupling on the same dashboard are the counterweight; without them the
+ * measure becomes a target.
+ */
+export type ModuleMetrics = {
+    module: string;
+    functionPoints: number;
+    /** transactions this module exposes */
+    transactions: number;
+    /** data stores this module declares */
+    dataStores: number;
+    /** modules this one depends on: its transactions reach their data */
+    dependsOn: string[];
+    /** modules that depend on this one */
+    dependedOnBy: string[];
+    /**
+     * Martin's instability: `Ce / (Ca + Ce)`.
+     *
+     * 0 means stable (everyone depends on it, it depends on nobody); 1 means
+     * unstable. A stable module that changes often is where change hurts.
+     */
+    instability: number;
+};
+export type StructureMetrics = {
+    modules: ModuleMetrics[];
+    /** module pairs with mutual dependency — cycle candidates */
+    mutualDependencies: [string, string][];
+    /** function points per data store: functional density */
+    pointsPerDataStore: number;
+    /** transactions per store: how much each entity is exercised */
+    transactionsPerDataStore: number;
+};
+export declare function measureStructure(inventory: Inventory, count: CountResult): StructureMetrics;
+/**
+ * Conformance to the application's own conventions.
+ *
+ * Measures neither size nor quality: it measures whether the team follows what
+ * it agreed on. It comes free from the inventory, and in a software factory it
+ * is what turns into a standards audit.
+ */
+export type Conformance = {
+    /** write transactions whose input fields come from a validator */
+    writesWithValidator: {
+        ok: number;
+        total: number;
+        ratio: number;
+    };
+    /** entry points whose handler was resolved */
+    entryPointsWithHandler: {
+        ok: number;
+        total: number;
+        ratio: number;
+    };
+    /** data stores reached by at least one transaction */
+    dataStoresReached: {
+        ok: number;
+        total: number;
+        ratio: number;
+    };
+};
+export declare function measureConformance(inventory: Inventory): Conformance;

package/build/src/pipeline.d.ts

@@ -0,0 +1,44 @@
+import type { CountOptions } from './albrecht/counter.js';
+import type { CallResolver } from './inventory/resolvers/types.js';
+import type { CountResult, Inventory } from './types.js';
+/**
+ * The whole pipeline, in one place.
+ *
+ * Ace commands stay thin on purpose: they hold no logic and only print what
+ * this module returns. That is what makes it possible to test counting without
+ * booting an AdonisJS application — fixtures do not boot.
+ *
+ * The order is not arbitrary. Data stores come before any handler analysis,
+ * because `Model.create()` and `Service.create()` are indistinguishable by
+ * shape; and counting comes last, because ILF vs EIF depends on HOW
+ * transactions use each store (AFP §6.5.4).
+ */
+export type AnalysisOptions = CountOptions & {
+    /** call-graph depth from the handler */
+    maxDepth?: number;
+    /** custom tracing strategies, running before the built-in ones */
+    resolvers?: {
+        call?: CallResolver[];
+    };
+    /**
+     * Minimum tracing coverage. Below it the analysis fails rather than emitting
+     * a number that looks right.
+     */
+    minCoverage?: number;
+    /**
+     * Configuration file that produced these options, recorded in the count's
+     * `source`. The pipeline does not read it — the front-ends do — but the
+     * artefact has to say which configuration shaped the number.
+     */
+    configFile?: string | null;
+};
+export type Analysis = {
+    inventory: Inventory;
+    count: CountResult;
+};
+export declare class CoverageTooLowError extends Error {
+    readonly ratio: number;
+    readonly minimum: number;
+    constructor(ratio: number, minimum: number);
+}
+export declare function analyze(root: string, options?: AnalysisOptions): Promise<Analysis>;

package/build/src/pipeline.js

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

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

@@ -0,0 +1,6 @@
+import type { CountResult, CountedFunction } from '../types.js';
+import type { FunctionPointDiff } from '../albrecht/diff.js';
+export declare function renderCount(result: CountResult): string;
+/** `fp:explain`: a function's provenance, which is what supports a dispute */
+export declare function renderExplain(fn: CountedFunction): string;
+export declare function renderDiff(diff: FunctionPointDiff): string;

package/build/src/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Domain model of the package.
+ *
+ * Two deliberately independent layers:
+ *
+ *   Inventory  — raw facts extracted from the application. Knows nothing of FPA.
+ *   Albrecht   — IFPUG/AFP rules applied over the inventory.
+ *
+ * `src/inventory/**` must never import from `src/albrecht/**`.
+ */
+export type Provenance = {
+    file: string;
+    line?: number;
+    /** name of the collector/resolver/detector that produced the fact */
+    by: string;
+};
+export type { CountSource } from './inventory/source.js';
+import type { CountSource } from './inventory/source.js';
+/** A logical data store persisted by the application. */
+export type DataStore = {
+    id: string;
+    /** name as the user would recognise it (model, table) */
+    name: string;
+    module: string;
+    /** physical table, when known */
+    table?: string;
+    /** persisted attributes, excluding technical identifiers */
+    attributes: Attribute[];
+    /** candidate logical subgroups (composition relations) */
+    subgroups: string[];
+    /**
+     * Declared relations: property name -> target store name.
+     *
+     * This is what allows `.preload('author')` to resolve to the `Author` store.
+     * Without it, a table read only through a relation is reached by no
+     * transaction and drops out of the count under AFP §6.5.4 — when it is in
+     * fact a legitimate EIF.
+     */
+    relations: Record<string, string>;
+    /** maintained by this application, or by an external system? */
+    maintainedExternally: boolean;
+    provenance: Provenance;
+};
+export type Attribute = {
+    name: string;
+    type?: string;
+    isIdentifier: boolean;
+    provenance: Provenance;
+};
+/**
+ * An application entry point: HTTP route, ace command, job, listener.
+ * Transactions are not only HTTP — a scheduled command that imports a file is
+ * as transactional as a POST.
+ */
+export type EntryPoint = {
+    id: string;
+    kind: 'http' | 'command' | 'job' | 'listener';
+    module: string;
+    /** HTTP verb, command name, event name… */
+    trigger: string;
+    /** route pattern, command signature… */
+    signature: string;
+    /** route name when present; not the identity used across versions */
+    name?: string;
+    handler: HandlerRef | null;
+    provenance: Provenance;
+};
+export type HandlerRef = {
+    file: string;
+    /** class method; absent for single-action handlers */
+    member?: string;
+    /**
+     * Body line, for a handler with no name: an inline closure declared on the
+     * route itself (`router.get('/', ({ response }) => …)`).
+     *
+     * Its body is business code like any other and must be walked by the graph.
+     */
+    line?: number;
+};
+/** What the code reachable from an EntryPoint actually does. */
+export type HandlerBehavior = {
+    entryPointId: string;
+    /** does it write to any DataStore inside the boundary? */
+    writes: boolean;
+    /** DataStores reached (ids) */
+    touches: string[];
+    /** declared input fields (validators) */
+    inputFields: Field[];
+    /** declared output fields (transformers, DTOs) */
+    outputFields: Field[];
+    /** path walked through the call graph — what `fp:explain` prints */
+    trace: TraceStep[];
+    /** calls no resolver knew how to follow */
+    unresolved: UnresolvedCall[];
+};
+export type Field = {
+    name: string;
+    optional?: boolean;
+    provenance: Provenance;
+};
+export type TraceStep = {
+    file: string;
+    member?: string;
+    depth: number;
+    /** resolver that produced this step */
+    by: string;
+    writes: boolean;
+};
+/**
+ * A call the graph could not follow.
+ *
+ * This is NOT log noise — it is the inventory's coverage metric. Many
+ * unresolved calls mean an unreliable count, and the report must say so rather
+ * than feign precision.
+ */
+export type UnresolvedCall = {
+    file: string;
+    line: number;
+    expression: string;
+    reason: string;
+};
+export type Inventory = {
+    /** format version, for diffs across releases */
+    version: 1;
+    generatedAt: string;
+    app: string;
+    /** framework versions the count was made against — goes into the report */
+    framework: {
+        core?: number;
+        lucid?: number;
+        orm: string;
+    };
+    dataStores: DataStore[];
+    entryPoints: EntryPoint[];
+    behaviors: HandlerBehavior[];
+    coverage: {
+        entryPointsTotal: number;
+        entryPointsResolved: number;
+        unresolvedCalls: number;
+        /** fraction of entry points whose handler was traced to completion */
+        ratio: number;
+    };
+};
+export type FunctionType = 'ILF' | 'EIF' | 'EI' | 'EO' | 'EQ';
+export type Complexity = 'low' | 'average' | 'high';
+export type CountedFunction = {
+    id: string;
+    name: string;
+    module: string;
+    type: FunctionType;
+    /** DET — data element types */
+    det: number;
+    /** RET for data functions, FTR for transactional ones */
+    refs: number;
+    complexity: Complexity;
+    points: number;
+    /**
+     * Hash of the implementation scope.
+     *
+     * This is what `fp:diff` compares to decide whether a function CHANGED. It
+     * combines normalised-AST hashes of the bodies reached, so formatting and
+     * comments are excluded: running a formatter must not produce an invoice.
+     *
+     * Absent for data functions, whose scope is the declaration itself.
+     */
+    scopeHash?: string;
+    /** why it was classified this way — feeds `fp:explain` */
+    rationale: Rationale;
+};
+export type Rationale = {
+    /** rule applied, e.g. 'afp:6.5.3 modifies a data store -> EI' */
+    rule: string;
+    /** where each DET came from */
+    detSources: string[];
+    /** where the FTR/RET came from */
+    refSources: string[];
+    /**
+     * Manual overrides applied via config, with the required justification.
+     *
+     * `fields` says which numbers the override actually replaced, so the report
+     * can mark the DET line and leave RET alone rather than implying both came
+     * from a person.
+     */
+    overrides?: {
+        reason: string;
+        by: string;
+        fields: ('det' | 'refs')[];
+    }[];
+    trace?: TraceStep[];
+};
+export type CountResult = {
+    /** identifies the rule set — counts are comparable only if these match */
+    ruleset: string;
+    rulesetVersion: string;
+    /**
+     * What was counted: application, revision, whether the tree was dirty.
+     *
+     * Optional because `count()` can be called directly with an inventory built
+     * by hand; every count the CLI writes carries it. Without it two saved counts
+     * are comparable in form and meaningless in substance — the same application
+     * a month apart looks exactly like a defect in the counter.
+     */
+    source?: CountSource;
+    functions: CountedFunction[];
+    totals: {
+        unadjusted: number;
+        byType: Record<FunctionType, {
+            count: number;
+            points: number;
+        }>;
+        byModule: Record<string, number>;
+    };
+    /** flags when the count does not deserve confidence */
+    confidence: {
+        unresolvedCalls: number;
+        entryPointsWithoutHandler: number;
+        warnings: string[];
+    };
+};
+/** Maintenance type, for enhancement-project counting. */
+export type ChangeType = 'added' | 'changed' | 'removed' | 'unchanged';
+/**
+ * Why a function counts as changed.
+ *
+ * The three causes used to collapse into one boolean, so a pure refactor and a
+ * genuine growth in functional size were indistinguishable in the report and
+ * priced identically. AEP does not ask for that collapse — it treats a type
+ * change separately and grades modification by effort — and a factory pricing
+ * a month of work needs to see which of the three it is paying for.
+ *
+ *   type            reclassified: ILF <-> EIF, EI <-> EO
+ *   size            DET or FTR moved, so the functional size really changed
+ *   implementation  same size, different code — refactoring
+ */
+export type ChangeReason = 'type' | 'size' | 'implementation';
+export type DiffEntry = {
+    function: CountedFunction;
+    change: ChangeType;
+    previous?: CountedFunction;
+    /** present only when `change` is 'changed' */
+    reason?: ChangeReason;
+};
+export type DiffResult = {
+    from: string;
+    to: string;
+    entries: DiffEntry[];
+    totals: Record<ChangeType, {
+        count: number;
+        points: number;
+    }>;
+    /** the `changed` total split by cause — where an invoice actually comes from */
+    changedByReason: Record<ChangeReason, {
+        count: number;
+        points: number;
+    }>;
+};

package/build/src/types.js

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

package/build/stubs/config.stub

@@ -0,0 +1,37 @@
+{{{
+  exports({ to: app.configPath('function_points.ts') })
+}}}
+import { defineConfig } from '@filipebraida/adonis-function-points'
+
+export default defineConfig({
+  /**
+   * The application boundary is a business decision, not a technical one.
+   * Review it with whoever signs the contract, not only with the team.
+   */
+  boundary: {
+    infrastructure: ['access_tokens', 'reset_password_tokens', 'audits'],
+    ignoreEntryPoints: ['drive.fs.serve', 'prometheus.metrics'],
+    externallyMaintained: [],
+  },
+
+  /** Logical subgroups (RET). `constant` pins it at 1, which is honest. */
+  retStrategy: 'constant',
+
+  /** How far to follow the call graph from the handler. */
+  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.
+   */
+  // overrides: {
+  //   'POST /petitions': { det: 42, reason: 'JSON Schema form; 42 user fields' },
+  // },
+})

package/build/tmp/probe.d.ts

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

package/build/tmp/probe_cli.d.ts

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

package/build/tmp/probe_cmp.d.ts

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

package/build/tmp/probe_count.d.ts

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

package/build/tmp/probe_data.d.ts

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

package/build/tmp/probe_diff.d.ts

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

package/build/tmp/probe_gap.d.ts

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

package/build/tmp/probe_graph.d.ts

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

package/build/tmp/probe_metrics.d.ts

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

package/build/tmp/probe_miss.d.ts

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

package/build/tmp/probe_names.d.ts

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

package/build/tmp/probe_nodata.d.ts

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

package/build/tmp/probe_one.d.ts

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

package/build/tmp/probe_perf.d.ts

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

package/build/tmp/probe_routes.d.ts

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

package/build/tmp/probe_unres.d.ts

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

package/build/tmp/probe_vazquez.d.ts

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

package/build/tsdown.config.d.ts

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