@filipebraida/adonis-function-points 0.1.0

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

@@ -0,0 +1,48 @@
+import type { AppContext } from '../inventory/app_context.js';
+import type { CollectedDataStore } from '../inventory/sources/data_stores.js';
+import type { CollectedEntryPoint } from '../inventory/sources/routes_ast.js';
+import type { Behavior } from '../inventory/graph/call_graph.js';
+import type { DiscoveredSchema } from '../inventory/sources/json_schemas.js';
+import type { Complexity, CountResult, FunctionType } from '../types.js';
+import type { FunctionOverride } from '../define_config.js';
+import type { ComplexityTable } from './tables.js';
+/**
+ * Assembles the count from the inventory.
+ *
+ * The order is not arbitrary: data functions depend on HOW transactions use
+ * each store (AFP §6.5.4), and transactional functions depend on which stores
+ * ended up counted. Hence: usage first, then the technical filter, then data,
+ * then transactions.
+ */
+export declare const RULESET = "afp";
+/**
+ * Version of the rule set.
+ *
+ * It appears in every report, and `fp:diff` refuses to compare counts produced
+ * by different versions — otherwise the difference would measure the rule
+ * change rather than the work.
+ */
+export declare const RULESET_VERSION = "1.0.0";
+export type CountInput = {
+    app: AppContext;
+    stores: CollectedDataStore[];
+    entryPoints: CollectedEntryPoint[];
+    /** behaviour keyed by `EntryPoint.id`; absent means no handler */
+    behaviors: Map<string, Behavior>;
+    /** JSON Schema literals found in the code, for `detFromSchema` — §8 */
+    jsonSchemas?: Map<string, DiscoveredSchema>;
+};
+export type CountOptions = {
+    retStrategy?: 'constant' | 'composition';
+    /** declared DET/RET for what static analysis cannot read — see §8 */
+    overrides?: Record<string, FunctionOverride>;
+    boundary?: {
+        infrastructure?: string[];
+        externallyMaintained?: string[];
+        ignoreEntryPoints?: string[];
+    };
+    messageDet?: number;
+    complexityTables?: Partial<Record<FunctionType, ComplexityTable>>;
+    weights?: Partial<Record<FunctionType, Record<Complexity, number>>>;
+};
+export declare function count(input: CountInput, options?: CountOptions): CountResult;

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

@@ -0,0 +1,32 @@
+import type { CollectedDataStore } from '../inventory/sources/data_stores.js';
+import type { Complexity, CountedFunction, FunctionType } from '../types.js';
+import type { ComplexityTable } from './tables.js';
+/**
+ * Data functions: ILF and EIF.
+ *
+ * The classification does not come from the model's own code — it comes from
+ * HOW the application's transactions use the store:
+ *
+ *   "If the Data Function is maintained by any of the application's
+ *    Transactional Functions, the Data Function shall be determined to be an
+ *    ILF. […] If a Data Function is not used in any of the processing of an
+ *    application's Transactional Functions, the Data Function shall not be
+ *    counted in the application."  — AFP §6.5.4
+ *
+ * That is why this module takes usage, not just the stores.
+ */
+export type StoreUsage = {
+    /** does any transaction of the application write to this store? */
+    written: boolean;
+    /** does any transaction reach it at all, reading or writing? */
+    used: boolean;
+};
+export type DataFunctionOptions = {
+    /** `constant` pins RET at 1; `composition` derives it from composition relations */
+    retStrategy: 'constant' | 'composition';
+    /** stores maintained by another system, by boundary decision */
+    externallyMaintained: Set<string>;
+    tables: Record<FunctionType, ComplexityTable>;
+    weights: Record<FunctionType, Record<Complexity, number>>;
+};
+export declare function countDataFunctions(stores: CollectedDataStore[], usage: Map<string, StoreUsage>, options: DataFunctionOptions): CountedFunction[];

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

@@ -0,0 +1,66 @@
+import type { ChangeType, CountResult, DiffResult } from '../types.js';
+/**
+ * Added, changed and removed functions between two counts — what becomes an
+ * invoice.
+ *
+ * Normative base: **OMG Automated Enhancement Points 1.0**, the sibling of AFP,
+ * written to size maintenance between two revisions.
+ *
+ *   "Each Artifact shall be analyzed in both revisions to determine whether it
+ *    is: Added — when it exists in revision ToRevision while it didn't exist in
+ *    FromRevision. […] Modified — when it exists in both revisions but whose
+ *    source code changed."  — AEP §6.3
+ *
+ * Two decisions make this workable:
+ *
+ * 1. **It operates on two saved counts**, never on two checkouts. Booting the
+ *    older revision, with possibly different dependencies, is the kind of
+ *    problem not worth solving.
+ * 2. **It refuses to compare different rule sets.** If the rules changed in
+ *    between, the difference measures the rule change, not the work — and the
+ *    result would go into an invoice.
+ */
+export declare class IncomparableRulesetsError extends Error {
+    constructor(from: string, to: string);
+}
+/**
+ * Factors per change type.
+ *
+ * The `added` and `removed` defaults are the explicit anchors of AEP §6.5: an
+ * added transaction is worth 1, a deleted one 0.4.
+ *
+ * `changed` defaults to 1 and **that overestimates**. AEP grades it from 0.25
+ * to 1.75 through Table 6.1, derived from Effort Complexity variation, which
+ * requires cyclomatic complexity that this package does not yet measure.
+ * Counting 1 is conservative in the sense of not inventing a number, not in the
+ * sense of billing less — and the result says so.
+ */
+export type ChangeFactors = Record<ChangeType, number>;
+export declare const AEP_FACTORS: ChangeFactors;
+export type DiffOptions = {
+    factors?: Partial<ChangeFactors>;
+    /** labels for the two measurements, for the report only */
+    labels?: {
+        from: string;
+        to: string;
+    };
+};
+export type FunctionPointDiff = DiffResult & {
+    /** function points weighted by the factors — this is what gets billed */
+    billable: number;
+    factors: ChangeFactors;
+    warnings: string[];
+};
+/**
+ * Two counts of DIFFERENT applications compare cleanly and mean nothing.
+ *
+ * The ruleset guard already refuses counts produced by different rules. This
+ * refuses counts produced over different subjects, which is the same class of
+ * error and the easier one to make in CI, where both files arrive as paths.
+ */
+export declare class IncomparableSourcesError extends Error {
+    readonly from: string;
+    readonly to: string;
+    constructor(from: string, to: string);
+}
+export declare function diffCounts(from: CountResult, to: CountResult, options?: DiffOptions): FunctionPointDiff;

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

@@ -0,0 +1,13 @@
+/**
+ * Counting engine — IFPUG / OMG-AFP lineage.
+ *
+ * "Albrecht" names the FAMILY of rules, not just the person: measurement
+ * literature says "Albrecht function points" to separate this lineage from
+ * COSMIC, which counts data movements and yields incompatible numbers.
+ *
+ * Normative reference: OMG Automated Function Points 1.0 / ISO/IEC 19515.
+ */
+export * from './tables.js';
+export * from './counter.js';
+export * from './diff.js';
+export * from './calibration.js';

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

@@ -0,0 +1,19 @@
+import type { Complexity, FunctionType } from '../types.js';
+/**
+ * IFPUG CPM complexity tables.
+ *
+ * Configurable on purpose. A single DET of difference — typically the
+ * confirmation message, which no static analyser can see — is enough to cross
+ * the low/average band and change a function's value. Calibrating the bands
+ * against manual counts is more honest than pretending the bias is absent.
+ */
+export type ComplexityTable = {
+    /** upper bounds of the RET/FTR bands: [a, b] => <=a | <=b | rest */
+    refBands: [number, number];
+    /** upper bounds of the DET bands */
+    detBands: [number, number];
+};
+export declare const DEFAULT_TABLES: Record<FunctionType, ComplexityTable>;
+export declare const DEFAULT_WEIGHTS: Record<FunctionType, Record<Complexity, number>>;
+export declare function complexityOf(type: FunctionType, refs: number, det: number, tables?: Record<FunctionType, ComplexityTable>): Complexity;
+export declare function pointsOf(type: FunctionType, complexity: Complexity, weights?: Record<FunctionType, Record<Complexity, number>>): number;

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

@@ -0,0 +1,25 @@
+import type { CollectedDataStore } from '../inventory/sources/data_stores.js';
+/**
+ * Temporary and technical data filter — AFP §6.5.2.1.1.
+ *
+ *   "Database tables identified as temporary or technical shall be marked as
+ *    such to be presented in the final report, and shall be ignored in the rest
+ *    of this process."
+ *
+ * Returns the reason when a table is technical, `null` otherwise: the report
+ * must say WHY something was excluded, not merely that it was.
+ */
+/**
+ * Naming conventions, with the defaults given by the spec itself (§6.5.2.1.3).
+ *
+ * The standard treats these as user-provided inputs, so they stay overridable
+ * through the boundary configuration.
+ */
+export declare const DEFAULT_TECHNICAL_PATTERNS: {
+    label: string;
+    pattern: RegExp;
+}[];
+export declare function isTechnical(store: CollectedDataStore, patterns?: {
+    label: string;
+    pattern: RegExp;
+}[]): string | null;

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

@@ -0,0 +1,35 @@
+import type { CollectedDataStore } from '../inventory/sources/data_stores.js';
+import type { CollectedEntryPoint } from '../inventory/sources/routes_ast.js';
+import type { Behavior } from '../inventory/graph/call_graph.js';
+import type { Complexity, CountedFunction, FunctionType } from '../types.js';
+import type { ComplexityTable } from './tables.js';
+/**
+ * Transactional functions: EI and EO.
+ *
+ *   "Transactions that modify data entities content shall be considered
+ *    External Inputs (EI). […] Transactions that do not modify data entities
+ *    content but only use them shall be considered as External Output."
+ *   — AFP §6.5.3
+ *
+ * There is no EQ here, and that is the standard's decision rather than a
+ * simplification of ours:
+ *
+ *   "Since the primary intent cannot be assessed by an automated function point
+ *    counting tool, all outputs and inquiries shall be counted as external
+ *    outputs (EO)."  — AFP §6.5.3
+ */
+export type TransactionOptions = {
+    /** stores that are counted; anything else contributes no FTR */
+    countedStores: Map<string, CollectedDataStore>;
+    /**
+     * Extra DET for the confirmation or error message.
+     *
+     * The IFPUG manual counts one; AFP does not. The default follows AFP, and it
+     * stays configurable because this is a known systematic divergence of −1 DET
+     * per transaction against manual counts.
+     */
+    messageDet: number;
+    tables: Record<FunctionType, ComplexityTable>;
+    weights: Record<FunctionType, Record<Complexity, number>>;
+};
+export declare function countTransactionalFunctions(entryPoints: CollectedEntryPoint[], behaviors: Map<string, Behavior>, options: TransactionOptions): CountedFunction[];

package/build/src/cli/load_config.d.ts

@@ -0,0 +1,28 @@
+import type { FunctionPointsConfig } from '../define_config.js';
+/**
+ * Loads `config/function_points.ts` from the application being analysed.
+ *
+ * Both front-ends need this and neither could do it alone: the ace commands run
+ * with `startApp: false`, so there is no booted container to read config from;
+ * and the standalone CLI has no container at all. The file is therefore
+ * imported directly, through jiti, which transforms the whole module graph —
+ * a config may import a resolver from the application, and that resolver may
+ * import files using decorators, which Node's type stripping cannot handle.
+ *
+ * **A config that exists and fails to load is an error, never a fallback.**
+ * Falling back to defaults with a warning would silently change the count, and
+ * the count becomes an invoice. Absence of a config file is a different thing,
+ * and is legitimate: it means the defaults.
+ */
+export declare const CONFIG_PATHS: string[];
+export declare class ConfigLoadError extends Error {
+    readonly file: string;
+    readonly cause: unknown;
+    constructor(file: string, cause: unknown);
+}
+export type LoadedConfig = {
+    config: FunctionPointsConfig;
+    /** absolute path of the file used, or null when the defaults apply */
+    file: string | null;
+};
+export declare function loadConfig(root: string): Promise<LoadedConfig>;

package/build/src/cli/print.d.ts

@@ -0,0 +1,19 @@
+import type { RunResult } from './runners.js';
+/**
+ * One place that decides how a `RunResult` reaches a terminal.
+ *
+ * Shared so the two front-ends cannot drift in what they show — including the
+ * failure path: a command that found nothing must exit non-zero in CI exactly
+ * as it does under ace.
+ */
+export type Printer = {
+    log: (message: string) => void;
+    error: (message: string) => void;
+    /**
+     * Diagnostics about the run itself — which config was used, calibration
+     * warnings. A separate channel because they must NOT land on stdout: `--json`
+     * exists to be piped, and a note printed there makes the output unparseable.
+     */
+    note: (message: string) => void;
+};
+export declare function printResult(result: RunResult, printer: Printer): number;

package/build/src/cli/runners.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What each command actually does, with no front-end attached.
+ *
+ * There are two front-ends — the ace commands, for a project that installed the
+ * package, and the standalone binary, for CI — and a rule that keeps them
+ * honest: **they must not be able to disagree**. Everything that decides a
+ * number lives here; the front-ends only parse arguments and print.
+ *
+ * Loading `config/function_points.ts` is part of that. It used to happen in
+ * neither front-end, so every option but `--min-coverage` was silently ignored
+ * by the command a user actually runs, while the tests proved the options
+ * worked by calling `analyze()` directly.
+ */
+export type RunResult = {
+    /** what to print on stdout */
+    output: string;
+    /** lines to report as errors; a non-empty list means failure */
+    errors?: string[];
+    /** notes about the run itself, printed before the output */
+    notes?: string[];
+};
+type Common = {
+    root: string;
+};
+export declare function runInventory(options: Common & {
+    out?: string;
+}): Promise<RunResult>;
+export declare function runCount(options: Common & {
+    out?: string;
+    json?: boolean;
+    minCoverage?: number;
+}): Promise<RunResult>;
+export declare function runExplain(options: Common & {
+    name: string;
+}): Promise<RunResult>;
+/**
+ * Compares a saved count against the current tree, or against a second saved
+ * count.
+ *
+ * The two-file form is the shape CI has: a pipeline counts the base revision
+ * and the head revision, and neither of them is "the current working tree" by
+ * the time they are compared. Since the analyser needs nothing installed in the
+ * application, counting an older revision is a `git worktree` away.
+ */
+export declare function runDiff(options: Common & {
+    previous: string;
+    current?: string;
+}): Promise<RunResult>;
+export declare function runCalibrate(options: Common & {
+    samples: string;
+}): Promise<RunResult>;
+export {};

package/build/src/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The package's own version, for `--version`.
+ *
+ * Walks up from this module until it finds a package.json, so it works both
+ * from source (`src/cli.ts`) and from the build (`build/src/cli.js`), which sit
+ * at different depths.
+ */
+export declare function packageVersion(): string;
+/** minimal parser: a flag is `--name value` or `--name=value`, plus booleans */
+export declare function parseArgv(argv: string[]): {
+    command: string;
+    positional: string[];
+    flags: Map<string, string | true>;
+};
+import type { Printer } from './cli/print.js';
+export declare function run(argv: string[], printer?: Printer): Promise<number>;
+export declare class UsageError extends Error {
+}
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli.js

@@ -0,0 +1,198 @@
+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 path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/cli.ts
+/**
+* Standalone entry point, for CI and for one-off runs with `npx`.
+*
+* It does NOT replace installing the package: a project that installs it keeps
+* the `node ace fp:*` commands. Both front-ends call the same runners, so they
+* cannot disagree about a number.
+*
+* Nothing is booted here either — the engine only ever reads files — which is
+* what makes a run possible with no `.env`, no database and no install in the
+* analysed project.
+*/
+const USAGE = `adonis-function-points — automated function point counting for AdonisJS
+
+Usage
+  adonis-function-points <command> [options]
+
+Commands
+  count                    count the unadjusted function points
+  inventory                the raw facts: stores, routes, tracing coverage
+  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
+                           compare the files, which is the shape CI has
+  calibrate <samples.csv>  correction factors against a manual count
+
+Options
+  --root <path>            application to analyse (default: the current directory)
+  --out <path>             write the result as JSON to this path
+  --json                   print JSON instead of a table
+  --min-coverage <0..1>    fail below this tracing coverage
+  -h, --help               this message
+  -v, --version            package version
+`;
+/**
+* The package's own version, for `--version`.
+*
+* Walks up from this module until it finds a package.json, so it works both
+* from source (`src/cli.ts`) and from the build (`build/src/cli.js`), which sit
+* at different depths.
+*/
+function packageVersion() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 6; depth++) {
+		const candidate = path.join(dir, "package.json");
+		if (existsSync(candidate)) {
+			const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+			if (parsed.version) return parsed.version;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return "unknown";
+}
+/** minimal parser: a flag is `--name value` or `--name=value`, plus booleans */
+function parseArgv(argv) {
+	const positional = [];
+	const flags = /* @__PURE__ */ new Map();
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (!token.startsWith("-")) {
+			positional.push(token);
+			continue;
+		}
+		const [key, inline] = token.replace(/^--?/, "").split("=");
+		if (inline !== void 0) {
+			flags.set(key, inline);
+			continue;
+		}
+		const next = argv[index + 1];
+		if (next && !next.startsWith("-")) {
+			flags.set(key, next);
+			index++;
+		} else flags.set(key, true);
+	}
+	return {
+		command: positional[0],
+		positional: positional.slice(1),
+		flags
+	};
+}
+const numeric = (value) => typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) ? Number(value) : void 0;
+const text = (value) => typeof value === "string" ? value : void 0;
+const CONSOLE = {
+	log: (message) => process.stdout.write(`${message}\n`),
+	error: (message) => process.stderr.write(`${message}\n`),
+	note: (message) => process.stderr.write(`${message}\n`)
+};
+async function run(argv, printer = CONSOLE) {
+	const { command, positional, flags } = parseArgv(argv);
+	if (flags.has("version") || flags.has("v")) {
+		printer.log(packageVersion());
+		return 0;
+	}
+	if (!command || flags.has("help") || flags.has("h")) {
+		printer.log(USAGE.trimEnd());
+		return command ? 0 : 1;
+	}
+	if (![
+		"count",
+		"inventory",
+		"explain",
+		"diff",
+		"calibrate"
+	].includes(command)) {
+		printer.error(`unknown command "${command}"`);
+		printer.log(USAGE.trimEnd());
+		return 1;
+	}
+	const root = path.resolve(text(flags.get("root")) ?? process.cwd());
+	/**
+	* Pointing at the wrong directory is the likeliest mistake in CI, and its
+	* symptom is a confident zero: a monorepo root has a package.json, so that
+	* check passed and the count came back 0 FP with 100% coverage and exit 0.
+	*
+	* `adonisrc.ts` is what actually marks an AdonisJS application root.
+	*/
+	/**
+	* `diff a.json b.json` analyses nothing: both sides are already counted. It
+	* runs in a pipeline step that may not even sit inside the application — the
+	* CI shape this exists for — so requiring an application root there would
+	* refuse the one case it was added for.
+	*/
+	const analysesTheTree = !(command === "diff" && positional.length >= 2);
+	const marker = ["adonisrc.ts", "adonisrc.js"].find((name) => existsSync(path.join(root, name)));
+	if (analysesTheTree && !marker) {
+		printer.error(`no adonisrc.ts in ${root}: this is not an AdonisJS application root.\nIn a monorepo, point --root at the application itself (apps/<name>).`);
+		return 1;
+	}
+	const need = (what, value) => {
+		if (!value) throw new UsageError(`${command} needs ${what}`);
+		return value;
+	};
+	let result;
+	switch (command) {
+		case "count":
+			result = await runCount({
+				root,
+				out: text(flags.get("out")),
+				json: flags.get("json") === true,
+				minCoverage: numeric(flags.get("min-coverage"))
+			});
+			break;
+		case "inventory":
+			result = await runInventory({
+				root,
+				out: text(flags.get("out"))
+			});
+			break;
+		case "explain":
+			result = await runExplain({
+				root,
+				name: need("a function name", positional[0])
+			});
+			break;
+		case "diff":
+			result = await runDiff({
+				root,
+				previous: need("a saved count", positional[0]),
+				current: positional[1]
+			});
+			break;
+		case "calibrate":
+			result = await runCalibrate({
+				root,
+				samples: need("a samples CSV", positional[0])
+			});
+			break;
+		/* c8 ignore next 2 -- unreachable: KNOWN is checked above */
+		default: return 1;
+	}
+	return printResult(result, printer);
+}
+var UsageError = class extends Error {};
+async function main(argv = process.argv.slice(2)) {
+	try {
+		return await run(argv, CONSOLE);
+	} catch (error) {
+		/**
+		* These three are not crashes — they are the package refusing to produce a
+		* number it cannot stand behind. They deserve their message, not a stack.
+		*/
+		if (error instanceof UsageError || error instanceof ConfigLoadError || error instanceof CoverageTooLowError) {
+			process.stderr.write(`${error.message}\n`);
+			return 1;
+		}
+		process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : error}\n`);
+		return 1;
+	}
+}
+//#endregion
+export { UsageError, main, packageVersion, parseArgv, run };